From ad710ed143e64d99ff4aaf7fde047330369041bd Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Fri, 13 Nov 2026 07:10:24 +0000 Subject: [PATCH] :books: 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 --- .serena/memories/workflow/creating-commits.md | 8 ++++++ .serena/memories/workflow/creating-prs.md | 15 +++++++++++ CONTRIBUTING.md | 25 ++++++++++++++++--- 3 files changed, 45 insertions(+), 3 deletions(-) diff --git a/.serena/memories/workflow/creating-commits.md b/.serena/memories/workflow/creating-commits.md index cf08358aaf..d225217867 100644 --- a/.serena/memories/workflow/creating-commits.md +++ b/.serena/memories/workflow/creating-commits.md @@ -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 ` as described in `mem:workflow/creating-prs`; do not rely on the keyword to create that link. diff --git a/.serena/memories/workflow/creating-prs.md b/.serena/memories/workflow/creating-prs.md index 87f10f2121..e8e34181e6 100644 --- a/.serena/memories/workflow/creating-prs.md +++ b/.serena/memories/workflow/creating-prs.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b23ae0fa9..27ec89998b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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: