From 8fa191775341983a680f5ea829dcade4af7c8d17 Mon Sep 17 00:00:00 2001 From: meh Date: Sun, 26 Jul 2026 05:34:26 +0700 Subject: [PATCH 1/2] docs: forbid merge commits, prefer rebase when landing PRs Two rules that were practice but not written down, so an agent had no way to follow them. Merge commits: refreshing a feature branch with `git merge master` adds a commit whose only content is that you were behind, and turns a readable line of work into a diamond. Rebase onto the moved base instead. The existing force-push bullet already blessed rebasing; this says plainly that merging is not the alternative. Landing PRs: prefer rebase over squash. Individual commits record what was tried and in what order; squashing collapses that into one message that can only summarise. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c07ab92..1ee533e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,6 +82,17 @@ to every agent and human; private memory dies with your machine. `--force-with-lease` so you don't clobber someone else's push. - **Never force-push the default branch** (`main`/`master`). That is the history everyone else builds on, and it is protected server-side for a reason. +- **Never create merge commits.** Not locally, not to refresh a branch. If your branch + has fallen behind, **rebase** it onto the moved base (`git rebase origin/master`, then + `--force-with-lease`). `git merge master` into a feature branch is not an acceptable + shortcut: it adds a commit whose only content is the fact that you were behind, and it + turns a readable line of work into a diamond. Merge commits are disabled server-side on + these repositories — that is a backstop, not a licence to rely on it. +- **Land pull requests with rebase, not squash.** Individual commits carry information: + what was tried, in what order, and why. Squashing throws that away and leaves one + commit whose message can only summarise. Write commits worth keeping, then land them + intact. Reach for squash only when a branch is genuinely one logical change scattered + across fixup commits. ## Guardrails From 5997e73af9c37074549c5e787356eedc343544d6 Mon Sep 17 00:00:00 2001 From: meh Date: Sun, 26 Jul 2026 05:49:28 +0700 Subject: [PATCH 2/2] docs: harden the merge ban, loosen the squash rule The first pass overstated the squash rule as "rebase, not squash" and allowed it only for fixup-heavy branches. The actual policy is looser: rebase is the default everywhere, squash is a judgement call and fine where it makes things easier or fits the branch better. The merge-commit ban goes the other way and is now stated as absolute -- not locally, not to refresh a branch, not to land a PR. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1ee533e..28c5e22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,17 +82,21 @@ to every agent and human; private memory dies with your machine. `--force-with-lease` so you don't clobber someone else's push. - **Never force-push the default branch** (`main`/`master`). That is the history everyone else builds on, and it is protected server-side for a reason. -- **Never create merge commits.** Not locally, not to refresh a branch. If your branch +- **Never create merge commits — this is a hard ban.** Not locally, not to refresh a + branch, not to land a pull request. If your branch has fallen behind, **rebase** it onto the moved base (`git rebase origin/master`, then `--force-with-lease`). `git merge master` into a feature branch is not an acceptable shortcut: it adds a commit whose only content is the fact that you were behind, and it turns a readable line of work into a diamond. Merge commits are disabled server-side on these repositories — that is a backstop, not a licence to rely on it. -- **Land pull requests with rebase, not squash.** Individual commits carry information: - what was tried, in what order, and why. Squashing throws that away and leaves one - commit whose message can only summarise. Write commits worth keeping, then land them - intact. Reach for squash only when a branch is genuinely one logical change scattered - across fixup commits. +- **Rebase is the default everywhere** — refreshing a branch, and landing a pull request. + Individual commits carry information: what was tried, in what order, and why. A rebase + merge keeps that granularity on the base branch, so write commits worth keeping and land + them intact. +- **Squash is acceptable** where it genuinely makes things easier or is the more + appropriate shape for the branch — one logical change scattered across fixup commits, or + a long branch whose intermediate states aren't worth preserving. It is a judgement call, + not a violation. Merging is the only thing that is never allowed. ## Guardrails