From 1d2d9a924acea524884faa4c8471ff41faa5d010 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Mon, 9 Mar 2026 09:32:35 +0100 Subject: [PATCH] docs: Add collection branch safety warnings to PR workflow Add explicit warnings to pr.mdc and create-java-pr skill that the collection branch must never be manually merged or fast-forwarded. Updating it causes GitHub to auto-merge all stack PRs and delete their branches, destroying the entire stack. Co-Authored-By: Claude --- .claude/skills/create-java-pr/SKILL.md | 2 ++ .cursor/rules/pr.mdc | 8 ++++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-java-pr/SKILL.md b/.claude/skills/create-java-pr/SKILL.md index b0fc12a5d2..9a0bf71eec 100644 --- a/.claude/skills/create-java-pr/SKILL.md +++ b/.claude/skills/create-java-pr/SKILL.md @@ -35,6 +35,8 @@ Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`, **For stacked PRs:** For the first PR in a new stack, first create and push the collection branch (see `.cursor/rules/pr.mdc` § "Creating the Collection Branch"), then branch the PR off it. For subsequent PRs, branch off the previous stack branch. Use the naming conventions from `.cursor/rules/pr.mdc` § "Branch Naming". +**CRITICAL: Never merge, fast-forward, or push commits into the collection branch.** It stays at its initial position until the user merges stack PRs through GitHub. Updating it will auto-merge and destroy the entire PR stack. + ## Step 2: Format Code and Regenerate API Files ```bash diff --git a/.cursor/rules/pr.mdc b/.cursor/rules/pr.mdc index 3b8f73194b..d1926a640f 100644 --- a/.cursor/rules/pr.mdc +++ b/.cursor/rules/pr.mdc @@ -185,6 +185,8 @@ git push -u origin HEAD gh pr create --base main --draft --title "(): " --body "Collection PR for the stack. Squash-merge this once all stack PRs are merged." ``` +**CRITICAL: Do NOT manually update the collection branch.** Never merge, fast-forward, or push stack branch commits into the collection branch. The collection branch stays at its initial position (the empty commit on `main`) until the user merges individual stack PRs into it one by one through GitHub. If you fast-forward the collection branch to include stack commits, GitHub will auto-merge and delete all stack PR branches, destroying the entire stack. + ### Creating a New Stacked PR 1. Start from the tip of the previous stack branch (or the collection branch for the first PR). @@ -237,12 +239,12 @@ Once all stack PRs are merged into the collection branch, the collection PR is * ### Syncing the Stack -When a base PR changes (e.g. after addressing review feedback on PR 1), merge the changes forward through the stack: +When a base PR changes (e.g. after addressing review feedback on PR 1), merge the changes forward through the stack **between adjacent stack PR branches only**: ```bash # On the branch for PR 2 git checkout feat/scope-attributes-logger -git merge feat/scope-attributes +git merge feat/scope-attributes-api git push # On the branch for PR 3 @@ -251,4 +253,6 @@ git merge feat/scope-attributes-logger git push ``` +**Never merge into the collection branch.** Syncing only happens between stack PR branches. The collection branch is untouched until the user merges PRs through GitHub. + Prefer merge over rebase — it preserves commit history, doesn't invalidate existing review comments, and avoids the need for force-pushing. Only rebase if explicitly requested.