From b0daec2df1667b9501aad77fa5833bcd49fd630e Mon Sep 17 00:00:00 2001 From: Rasmus Widing Date: Wed, 29 Apr 2026 15:12:16 +0300 Subject: [PATCH] docs(release-skill): warn against --ff-only and reset --hard for dev/main sync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SKILL's Step 9 already uses the correct primitive (`git pull origin main`, which creates a regular merge commit), but doesn't explicitly warn against the two trap doors that bit us during v0.3.10: 1. `git pull origin main --ff-only` — used by the experimental archon-release workflow's sync-dev-with-main step. Fast-forward is impossible across a squash merge; the workflow aborted on every release run. 2. `git reset --hard origin/main` — used during today's recovery as a "clean up the merge commit" workaround for #1. It worked locally but rewriting dev's history severed every open PR's merge-base, ballooning their diffs from <100 lines to thousands. Confirmed: PR #1444 went from +80/-1 to +6626/-300, restored after a recovery merge that re-attached the original release commits to dev. Add explicit DO-NOT block under the existing "Important" callout. Also document the conflict-resolution gotcha: when the merge conflicts on homebrew/archon.rb, use `git checkout origin/main -- ...` (NOT local `main`, which is typically stale because the release pushes via `git push origin dev:main` without fast-forwarding local main). The workflow-level fixes for both traps landed in #1490. This is the documentation companion so a future maintainer (or AI agent) doesn't repeat either trap. --- .claude/skills/release/SKILL.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 1844336f2f..19dd434e6c 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -255,6 +255,21 @@ git push origin dev > commit to dev — it does not bring the PR merge commit onto dev. This manual > `git pull origin main` is what ensures dev has the merge commit. +> **Do NOT** use `git pull origin main --ff-only` or `git reset --hard origin/main` +> for this sync. Fast-forward is impossible across a squash merge — main's squash +> commit has a different SHA than dev's release commit, so dev is never +> fast-forwardable to main. And resetting dev to main rewrites dev's history, +> which severs every open PR's merge-base from its original commit and balloons +> their diffs to thousands of lines (confirmed against v0.3.10's release: PRs +> went from `+80/-1` to `+6626/-300` after a `git reset --hard origin/main` on +> dev). The plain `git pull origin main` above creates a regular merge commit on +> dev. The merge bubble in dev's `git log` is the right cost for preserving +> open-PR sanity. If the merge produces a `homebrew/archon.rb` conflict during a +> recovery flow, resolve with `git checkout origin/main -- homebrew/archon.rb` +> (note: `origin/main`, NOT `main` — local main is often stale because the +> release pushes via `git push origin dev:main` without fast-forwarding the local +> branch). + The GitHub Release is distinct from the git tag — without it, the release won't appear on the repository's Releases page. Always create it. If the user merges the PR themselves and comes back, still offer to tag, release, and sync.