Skip to content

docs: require PR_TITLE and PR_BODY for squash merges #72

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
rianjs merged 2 commits into from
Aug 3, 2026
Merged

docs: require PR_TITLE and PR_BODY for squash merges #72

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
8da4144
docs: require PR title and body for squash merges
rianjs Aug 3, 2026
5cb1ed0
docs: align commit hygiene with squash settings
rianjs Aug 3, 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
15 changes: 10 additions & 5 deletions docs/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,16 @@ not auto-bump the minor and `fix:` does not auto-bump the patch; both simply
answer "does this merge ship?" The `MAJOR.MINOR` line is human-controlled in
`version.txt` and the patch is the CI run number (§2).

Squash-merge (`repo-layout.md` §6) means the **PR title is the commit that lands
on `main`**, so the PR title MUST be a conventional commit. This is enforced by
a **CI check on pull requests** (`ci.md` §2) — a local `commit-msg` hook never
sees the squashed PR title, so the gate has to live in CI. Commit messages MUST
NOT mention AI tooling (`repo-layout.md` §7).
With the required squash settings (`squash_merge_commit_title=PR_TITLE` and
`squash_merge_commit_message=PR_BODY`; see `repo-layout.md` §6), the **PR title
is the commit subject and the PR body is the body of the commit that lands on
`main`**. `PR_TITLE` is load-bearing: GitHub's `COMMIT_OR_PR_TITLE` option can
choose the lone commit subject for a one-commit squash PR, so a conventional
commit subject can bypass validation of a non-conventional PR title. The PR
title MUST therefore be a conventional commit. This is enforced by a **CI
check on pull requests** (`ci.md` §2) — a local `commit-msg` hook never sees the
squashed PR title, so the gate has to live in CI. Commit messages MUST NOT
mention AI tooling (`repo-layout.md` §7).

### §1.1 The shared commit grammar

Expand Down
15 changes: 9 additions & 6 deletions docs/repo-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,11 @@ defaults (no config file) is non-conformant.
### Merge settings
- **Squash merge only** (no merge commits, no rebase merge). This is why the PR
title must be a conventional commit (`release.md` §1).
- Set `squash_merge_commit_title=PR_TITLE` and

@rianjs-bot rianjs-bot Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new mandatory PR_BODY setting conflicts with §7's still-current description that the landing commit may contain either the PR description or branch commit messages, and that both squash-message modes are covered. That could lead maintainers to configure or reason about the prohibited commit-message mode. Update §7 to describe the now-required PR-title/PR-body shape and its corresponding CI coverage.

Reply inline to this comment.

@rianjs rianjs Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 5cb1ed0: §7 now describes only the required PR_TITLE/PR_BODY landing shape and the corresponding PR title/body CI coverage. The prohibited COMMIT_MESSAGES alternative is no longer presented. make check passes.

`squash_merge_commit_message=PR_BODY`. `COMMIT_OR_PR_TITLE` is prohibited:
for a one-commit squash PR it can select the lone commit subject instead of
the validated PR title and bypass the `pr-title` check. `PR_BODY` keeps the
validated PR body as the squash commit body.
- **Delete branch on merge.**

---
Expand All @@ -211,12 +216,10 @@ defaults (no config file) is non-conformant.
- Commit messages MUST NOT mention AI tooling (Claude, Anthropic, ChatGPT,
Copilot, etc.). Enforce with a `commit-msg` hook that greps a blocklist and
rejects on match. The hook alone is insufficient under squash merge: the
landing commit is built from the PR title plus, depending on the
squash-message setting, either the PR description or the branch's commit
messages — and the local hook sees only the last of those. The CI
`pr-title` check therefore greps the PR title and body against the same
blocklist (`ci.md` §2); between the two enforcement points every
squash-message mode is covered. Reference implementation (track it as
required `PR_TITLE` / `PR_BODY` settings build the landing commit from the PR
title and body, neither of which the local hook sees. The CI `pr-title` check
therefore greps both against the same blocklist (`ci.md` §2). Reference
implementation (track it as
`scripts/hooks/commit-msg` and wire via `git config core.hooksPath scripts/hooks`):

```sh
Expand Down
Loading