docs: make the release commands copy-pasteable and correct the invariant
Copilot review: - `<x.y.z>` / `<major|minor|patch>` inside a bash block is shell redirection, so both documented commands were syntax errors if copied. Verified: `bash -n` rejects `git tag <x.y.z> && ...` and accepts `git tag 2.3.0 && ...`. Use a concrete 2.2.0 -> 2.3.0 example and say what to substitute. - "agree on the version at every point" / "never disagree" overstated it. The procedure deliberately bumps v2/main first, so between the bump and the milestone merge the branches differ — v2/main reads the version being built, main the one released. Describe the real invariant: they converge when the release merge lands, and v2/main is never left behind main. Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
parent
9048e69758
commit
4d567c97e4
1 changed files with 9 additions and 5 deletions
|
|
@ -465,7 +465,7 @@ Don't lean on GitHub's permission gate to enforce this. Whether an outside repor
|
|||
|
||||
So v2 flows `feature branch → v2/main → (milestone) main → npm latest`, while v1 is flat: `feature branch → v1/main → npm v1-latest`, with no merge into `main` at any point. The two lines are published independently under separate dist-tags, which is why a v1 fix does **not** need to be forward-ported to reach users on v1 (`npx @modelcontextprotocol/inspector@v1-latest`).
|
||||
|
||||
⚠️ **The version bump rides that same flow — it is made on `v2/main`, never on the milestone-merge branch (#2010).** `npm version <x> --no-git-tag-version` lands on `v2/main` *before* the milestone merge, so the bump reaches `main` as part of the milestone's work and the two branches never disagree about the version; the release tag is then applied to the resulting **`main`** commit. Bumping on the milestone-merge branch instead (which is cut from `main`) puts the bump only downstream of `v2/main`, where nothing carries it back — that is how `v2/main` sat at `2.0.0` through both the 2.1.0 and 2.2.0 releases, and how #2009 came to carry an unrelated `2.0.0 → 2.2.0` diff simply because its branch was cut from a milestone-merge branch. **Never close a drift by merging `main` into `v2/main`**: `main` holds the whole pre-v2 v1 history (~230 commits `v2/main` lacks), so a back-merge grafts all of it into the develop branch permanently to deliver a two-file change. Full procedure in the root README's [Cutting a release](./README.md#cutting-a-release).
|
||||
⚠️ **The version bump rides that same flow — it is made on `v2/main`, never on the milestone-merge branch (#2010).** `npm version <x> --no-git-tag-version` lands on `v2/main` *before* the milestone merge, so the bump reaches `main` as part of the milestone's work; the release tag (bare `x.y.z`, no `v` prefix) is then applied to the resulting **`main`** commit. This deliberately leaves a normal in-flight interval where `v2/main` reads the version being built and `main` the one currently released — that difference is expected. The invariant it buys is that they converge when the release merge lands, so `v2/main` is never left *behind* `main` afterwards. Bumping on the milestone-merge branch instead (which is cut from `main`) puts the bump only downstream of `v2/main`, where nothing carries it back — that is how `v2/main` sat at `2.0.0` through both the 2.1.0 and 2.2.0 releases, and how #2009 came to carry an unrelated `2.0.0 → 2.2.0` diff simply because its branch was cut from a milestone-merge branch. **Never close a drift by merging `main` into `v2/main`**: `main` holds the whole pre-v2 v1 history (~230 commits `v2/main` lacks), so a back-merge grafts all of it into the develop branch permanently to deliver a two-file change. Full procedure in the root README's [Cutting a release](./README.md#cutting-a-release).
|
||||
|
||||
A corollary for **branching**: cut feature branches from **`v2/main`**, never from a milestone-merge branch — the latter carries release-only commits that will show up in your PR's diff.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue