mirror of
https://github.com/penpot/penpot.git
synced 2026-11-16 15:11:17 +00:00
📚 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:
parent
9bac1d290b
commit
ad710ed143
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user