From fc6bd0d1d4f48e40b379869e5f23edf3c474f1c4 Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 4 Jun 2026 01:07:22 -0500 Subject: [PATCH] fix(docs): correct sync-dev-after-release docs to match PR-based flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #28 refactored `scripts/sync-dev-after-release.sh` from direct-commit-to-dev to PR-based flow (cuts a `chore/sync-dev-after-vX.Y.Z` branch and opens a PR), but the accompanying documentation in `RELEASES.md` and `RELEASES-RATIONALE.md` still describes the old direct-commit shape. Bring both docs in sync with the shipped script. `RELEASES.md` § "After publish — sync dev with the release": - Replace "commits the result directly to `dev` as one signed commit (no PR)" with "cuts a `chore/sync-dev-after-vX.Y.Z` branch off `dev` and opens a PR". - Add a pointer to the rationale section explaining the PR-only norm applies here too. - Update the idempotency line from "exits 0 with no commit" to "exits 0 without creating a branch or PR" to match the script's actual short-circuit behaviour. `RELEASES-RATIONALE.md` § "Why backport `main` -> `dev` after publish": - Replace the "lands directly on `dev` (one signed commit, no PR). This is a deliberate exception to the PR-only norm" paragraph with the current behaviour: the backport opens a PR, the PR-only norm applies, the mechanical-diff and idempotency arguments justify reviewer spot-check + squash-merge rather than the prior exception-from-norm framing. - Same idempotency-line correction as RELEASES.md. No script changes; this PR only updates the prose that lagged the script. --- RELEASES-RATIONALE.md | 15 ++++++++------- RELEASES.md | 7 ++++--- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/RELEASES-RATIONALE.md b/RELEASES-RATIONALE.md index 6bee33c..88fc9f9 100644 --- a/RELEASES-RATIONALE.md +++ b/RELEASES-RATIONALE.md @@ -152,13 +152,14 @@ baseline — confusing during review, and load-bearing in two places: (a) `bin/c `UPGRADE_AVAILABLE` on a current main; (b) the `chore(spec)` re-vendor commit message references the current bundle version. -The backport lands directly on `dev` (one signed commit, no PR). This is a deliberate exception to the PR-only norm on -`dev` documented in [`RELEASES.md`](./RELEASES.md) — the change is mechanical (no design content) and the script's -idempotency makes it safe to re-run. The exception holds only for this script's output; everything else still lands on -`dev` via PR. - -The script is idempotent: it exits 0 with no commit when `VERSION` and `CHANGELOG.md` already match `main`. Safe to -re-run, safe to invoke from automation that doesn't track whether the last release was already backported. +The backport opens a PR against `dev` (`chore/sync-dev-after-vX.Y.Z`); it does **not** commit directly to `dev`. The +PR-only norm on `dev` documented in [`RELEASES.md`](./RELEASES.md) applies here as it applies to everything else. The +diff is mechanical (just `VERSION` + `CHANGELOG.md` copied from main), so reviewers can spot-check and squash-merge as +usual; the script's idempotency also makes the work safe to re-run if a maintainer pulls before merging the sync PR. + +The script is idempotent: it exits 0 without creating a branch or PR when `VERSION` and `CHANGELOG.md` already match +`main`. Safe to re-run, safe to invoke from automation that doesn't track whether the last release was already +backported. Mirror of `~/dev/agentnative-cli/scripts/sync-dev-after-release.sh`. The cli variant additionally regenerates `Cargo.lock` via `cargo build --release` after surgically updating `Cargo.toml`'s `[package].version`; the skill bundle diff --git a/RELEASES.md b/RELEASES.md index bc320ee..89b9e94 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -162,11 +162,12 @@ Once the release tag is published, backport the release-bookkeeping files from ` git push origin dev ``` -The script overwrites `VERSION` with the released number and copies `CHANGELOG.md` verbatim from `origin/main`, then -commits the result directly to `dev` as one signed commit (no PR). Without this step `dev`'s `VERSION` and +The script overwrites `VERSION` with the released number, copies `CHANGELOG.md` verbatim from `origin/main`, cuts a +`chore/sync-dev-after-vX.Y.Z` branch off `dev`, and opens a PR (the PR-only convention on `dev` applies here too — see +`RELEASES-RATIONALE.md` § Why backport main → dev after publish for why). Without this step `dev`'s `VERSION` and `CHANGELOG.md` stay frozen at the pre-release state, and future feature branches inherit the wrong baseline. -The backport is idempotent: re-running on a `dev` already in sync exits 0 with no commit. +The backport is idempotent: re-running on a `dev` already in sync exits 0 without creating a branch or PR. → Rationale: [`RELEASES-RATIONALE.md` § Why backport `main` → `dev` after publish](./RELEASES-RATIONALE.md#why-backport-main--dev-after-publish).