📚 Document the squash-merge default and the no-squash opt-out

Squash merge appeared twice in the guide, as a review-process bullet and
in branch naming, with no reason and no way out. Add a Merging
subsection: one PR lands as one atomic commit, so the history stays
readable and git bisect never stops on an intermediate commit that fails
the tests or the linter. A contributor who keeps every commit
self-contained may ask for a regular merge in the first line of the PR
description.

Record the same contract in mem:workflow/creating-prs (merge strategy,
and the Merge line above the AI Note line) and in
mem:workflow/creating-commits (what a self-contained commit means when a
regular merge is requested).

AI-assisted-by: deepseek-v4.1-flash
This commit is contained in:
Andrey Antukh 2026-11-13 07:10:24 +00:00
parent 9bac1d290b
commit ad710ed143
3 changed files with 45 additions and 3 deletions

View File

@ -56,6 +56,14 @@ that breaks them is wrong, even if the code is right.
`:bug:` bug fix · `:sparkles:` enhancement · `:tada:` new feature · `:recycle:` refactor · `:lipstick:` cosmetic · `:ambulance:` critical fix · `:books:` docs · `:construction:` WIP · `:boom:` breaking · `:wrench:` config · `:zap:` perf · `:whale:` docker · `:paperclip:` other · `:arrow_up:` dep upgrade · `:arrow_down:` dep downgrade · `:fire:` removal · `:globe_with_meridians:` translations · `:rocket:` epic/highlight
## Atomic Commits
A PR squash-merges into one commit by default, so the split inside the branch
does not reach `main` and nothing depends on it. When the PR asks for a
regular merge (`mem:workflow/creating-prs` → Merge Strategy), every commit
must stand alone: it builds, passes the linter, and needs no later commit on
the same branch to make sense.
## Referencing Issues
Use `Closes #NNNN` (not `Fixes #NNNN`) in commit and PR body text for readable context. The explicit issue-to-PR link is assigned with `python3 scripts/gh.py link-issue <ISSUE_NUMBER> <PR_NUMBER>` as described in `mem:workflow/creating-prs`; do not rely on the keyword to create that link.

View File

@ -32,6 +32,19 @@ PR titles follow commit title conventions:
See `mem:workflow/creating-commits` for emoji codes. Squash merge uses the PR title as the final commit subject, so title format matters.
## Merge Strategy
Policy: `CONTRIBUTING.md` → "Merging", under "Pull Requests".
- Squash merge is the default, so the PR's own commits never reach `main`
and the PR title becomes the landed subject.
- A regular merge is possible on request only. The request is the **first
line** of the PR body, above the `**Note:**` line:
`> **Merge:** do not squash; each commit is self-contained.`
- Ask for it only when every commit on the branch is self-contained (builds
and passes lint on its own). Default to squash unless the user asks for
the opposite.
## Description Body
Include concise sections covering:
@ -60,6 +73,8 @@ PR descriptions follow this structure:
```
The "Note:" line is required at the top. Adjust if this is a manual (non-AI) PR.
When the PR requests a regular merge instead of a squash merge, its
`**Merge:**` line goes above the `**Note:**` line (see Merge Strategy).
## Writing Principles

View File

@ -20,6 +20,7 @@ Center](https://help.penpot.app/).
- [Title format](#title)
- [Description](#description)
- [Review process](#review-process)
- [Merging](#merging)
- [What we won't accept](#what-we-wont-accept)
- [Good first issues](#good-first-issues)
- [Commit Guidelines](#commit-guidelines)
@ -111,8 +112,8 @@ Branch names are not enforced, but we recommend the following:
- Otherwise, use a short, descriptive name with words separated by hyphens
and no slashes (e.g. `fix-ellipse-icon-typo`, `feat-auto-link-libraries`).
Since PRs are squash-merged, the branch name does not survive into the
commit history — what matters is the [PR title](#title).
Since PRs are squash-merged by default, the branch name does not survive
into the commit history — what matters is the [PR title](#title).
### Format
@ -156,9 +157,27 @@ for more concrete information.
- Address review feedback by **pushing new commits** — do not
force-push during review, as it breaks comment threads.
- PRs require at least **one approval** before merge.
- We use **squash-merge** by default. The PR title becomes the final
- We **squash-merge** by default; see [Merging](#merging) for the reason
and for how to ask for a regular merge. The PR title becomes the final
commit message, so follow the [title format](#title) above.
### Merging
PRs are **squash-merged** by default. One PR lands as one commit, which keeps
the change atomic: the history stays readable, and `git bisect` never stops
on an intermediate commit that fails the tests or the linter.
This is the default, not a hard rule. If you keep your commits atomic and
self-contained — each one builds, passes the linter and makes sense on its
own — you may ask for a regular merge instead. Put the request in the first
line of the PR description, above everything else:
> **Merge:** do not squash; each commit is self-contained.
Maintainers honor the request when the commits hold up, and squash-merge
otherwise. After a squash merge the PR title becomes the commit subject on
the main branch; see [Title format](#title).
### What we won't accept
To save time on both sides, please avoid submitting PRs that: