From 9558168730463952b4329cf50930d11aa34f9875 Mon Sep 17 00:00:00 2001 From: bougyman's bot Date: Sat, 5 Sep 2026 10:14:59 -0400 Subject: [PATCH] docs: update docs to allow github merge commit titles --- app/usage-rules.md | 4 ++++ documents/phase-14-plan.adoc | 17 ++++++++++------- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/app/usage-rules.md b/app/usage-rules.md index 6d31650..013e9ef 100644 --- a/app/usage-rules.md +++ b/app/usage-rules.md @@ -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 `, and exactly matches `Merge branch '' into + `. - 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, diff --git a/documents/phase-14-plan.adoc b/documents/phase-14-plan.adoc index 37a43dc..0542b99 100644 --- a/documents/phase-14-plan.adoc +++ b/documents/phase-14-plan.adoc @@ -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 + `; and its subject is exactly `Merge branch '' + into `. 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.