Skip to content

docs(repo): record that the merged subject must be the validated one #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
justinmerrell merged 2 commits into from
Aug 25, 2026
Merged

docs(repo): record that the merged subject must be the validated one #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a117779
docs(repo): record that the merged subject must be the validated one
justinmerrell Aug 25, 2026
d486a47
Merge branch 'main' into docs/squash-title-invariant
justinmerrell Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions .github/rulesets/RULESETS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@ thread resolved. `0` is GitHub's sanctioned "no blanket reviewers" value, and
the code-owner requirement is evaluated per changed file.
[ADR 0015](../../docs/adr/0015-selective-code-owner-review.md) says why.

Six invariants keep the mechanism working. Each one breaks it *silently* — the
first four are checked by `task check:rulesets` (RUL-05..RUL-09); the last two
Seven invariants keep the mechanism working. Each one breaks it *silently* — the
first four are checked by `task check:rulesets` (RUL-05..RUL-09); the last three
are only visible against live GitHub state:

1. **No `*` catch-all in `.github/CODEOWNERS`.** It makes every pull request
Expand All @@ -83,6 +83,15 @@ are only visible against live GitHub state:
6. **No org-level ruleset may impose an approval count on this repository.**
Same aggregation. `spec` is deliberately absent from the org `pr-workflow`
ruleset's include list; do not add it.
7. **`squash_merge_commit_title` stays `PR_TITLE`.** It is a repository setting,
not a ruleset field, so nothing in this directory can carry it. Under the
default `COMMIT_OR_PR_TITLE`, a pull request with exactly one commit lands
*that commit's* subject rather than the title `Conventional PR title`
validated — so a subject no CI check ever read reaches `main`. It already
has: #67 was validated as `build(deps-dev): bump the tooling group …` and
landed as `Bump …`. Verify with `gh api repos/musher-dev/spec --jq
.squash_merge_commit_title`. See
[ADR 0016](../../docs/adr/0016-dependency-update-policy.md).

**An owner's own pull requests are exempt.** GitHub cannot request a review from
the author, so authorship waives the requirement for the patterns that author
Expand Down
25 changes: 22 additions & 3 deletions docs/adr/0016-dependency-update-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,26 @@ conventional-*shaped* prefix. Whether the type and scope in that prefix are real
remains the check's business; correcting them here would paper over exactly the
`dependabot.yml` bug described above.

### 4. Every copy of the vocabulary is checked, including the bot's
### 4. The merged subject is the one that was validated

`squash_merge_commit_title` moves from GitHub's default `COMMIT_OR_PR_TITLE` to
`PR_TITLE`. Under the default, a pull request with exactly one commit lands
*that commit's* subject rather than its title — and normalising the title does
nothing about Dependabot's commit message, which stays capitalised. #67 landed
on `main` as `build(deps-dev): Bump the tooling group across 1 directory with 5
updates` after being validated as `bump`. Decision 3 would have been true of
every pull request and false of every merge.

It is not only the bot's problem. Any single-commit pull request landed a
subject that only the local commit-msg hook had seen, and that hook checks the
type, not the case. `PR_TITLE` makes the string CI validates and the string that
reaches `main` the same string, for everyone.

Being a repository setting rather than a ruleset field, nothing in
`.github/rulesets/` can carry it; it is recorded as invariant 7 in
`.github/rulesets/RULESETS.md` with the command to verify it.

### 5. Every copy of the vocabulary is checked, including the bot's

`tools/src/commits.ts` now reads `.github/dependabot.yml` and
`.github/CONTRIBUTING.md` alongside the three files it already reconciled. A
Expand All @@ -125,7 +144,7 @@ A `commits` job in `.config/lefthook.yml` runs the check before the push as well
as in CI. The prefixes in `dependabot.yml` are exercised once a week by a bot
nobody watches, which is the longest possible feedback loop for a typo.

### 5. `wrangler` is excluded from the grouped update
### 6. `wrangler` is excluded from the grouped update

GOVERNANCE.md → Tooling dependencies names `wrangler` as the only dependency
here handed a credential, and rests its guarantee on that exact pin moving "only
Expand Down Expand Up @@ -169,7 +188,7 @@ revisiting the first time a major lands broken, not before.
Dependency updates merge on green CI without a bypass. They are correctly typed
and scoped, so they read as maintenance in `git log` and cannot cut a release.
The vocabulary now has five copies and a check that holds all five, rather than
three copies and two that drifted unobserved. `wrangler` moves only in a pull
three copies and two that drifted unobserved. What CI validates is what lands. `wrangler` moves only in a pull
request opened for it.

The normalisation step is not a gate; the action in the same job is. Because
Expand Down
Loading