Skip to content

docs: update docs to allow github merge commit titles #247

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
bougyman merged 1 commit into from
Sep 5, 2026
+14 −7
Merged

docs: update docs to allow github merge commit titles #247

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions app/usage-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
- Use the imperative, present tense in the description (`add`, not `added`/`adds`).
- Mark breaking changes with `!` before the colon (e.g. `feat!: ...`).
- Bare `Merge branch ...` subjects are rejected — reword as `chore: Merge branch ...`.
The sole exception is GitHub's auto-generated **Update branch** merge commit:
it is skipped only when it has two parents, was committed by
`GitHub <noreply@github.com>`, and exactly matches `Merge branch '<base>' into
<head>`.
- Enforced locally by the `commit-msg` hook at `git-hooks/commit-msg` (each
commit's own subject, via `ci/validate_conventional_subject.sh`) and the
`pre-push` hook at `git-hooks/pre-push` (every non-deletion ref update,
Expand Down
17 changes: 10 additions & 7 deletions documents/phase-14-plan.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,14 +115,17 @@ guarantees rather than a useful gate.
accepts an exact 40-character SHA so a GitHub push event can use
`github.event.before` and validate the new `main` commit rather than an empty
`main..main` range.
4. *No exception for non-conventional merge subjects.*
4. *Allow GitHub's trusted Update branch merge commit only.*
Bare `Merge branch ...` subjects fail like any other non-conventional
subject. The old validator exempted GitHub's update-branch merge commits,
but that contradicts the goal that every commit subject conform. A
contributor can rebase, or merge locally with a subject such as
`chore: Merge branch 'main' into my-branch`. Documentation must call out
this consequence because GitHub's Update branch button can create a subject
that the gate deliberately rejects.
subject, except for the exact merge commit generated by GitHub's *Update
branch* button. The range validator must skip that commit only when all of
these are true: it has exactly two parents; its committer is `GitHub
<noreply@github.com>`; and its subject is exactly `Merge branch '<base>'
into <head>`. The exception preserves the normal GitHub workflow without
allowing contributors to bypass Conventional Commit validation with an
ordinary merge commit. Its rationale and required regression coverage are
recorded in link:github-update-branch-validation-decision.adoc[the GitHub
Update branch validation decision].
5. *Local hooks are thin lifecycle adapters, not checks.*
`git-hooks/commit-msg` only resolves the repository and `exec`s
`ci/validate_conventional_subject.sh` with Git's message-file argument.
Expand Down