Release branching: main stays the trunk; release/vX.Y branches carry tagged releases and their patches; v1.1.1 back-ported to release/v1.1 #850

Decision, Brett Heap, 2026-10-17T19:52:26Z (in lane openRepoShape-3's session): "back-port to release/v1.1 as 1.1.1, open the issue". It answers his question of 19:49:52Z, on whether versioned tagged releases should use release branches. Lane 3 is the release owner.

The model

• main stays the trunk. Every pull request lands on main, as today. No version waits on another's tag, so the v1.1.1 freeze ends at the v1.1.0 tag.
• A release is a tag, not a branch. The version comes only from the tag (release.yml: v1.1.0 gives 1.1.0), so no branch or file carries a version number.
• A release branch per minor version. release/v1.1 is cut from the v1.1.0 tag. Each v1.1.x patch is tagged on it, while main heads toward v1.2.0.
• Back-ports. A fix bound for a patch lands on main first, through its own review, CI and gate. It is then back-ported to release/v1.1.
• release.yml already accepts this. A tag on release/v<major>.<minor> is accepted, and v1.0.1 was cut from release/v1.0 this way.

v1.1

1. v1.1.0 is tagged on main tonight, as planned: README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 lands last, then main's push run must be green, then the tag, release.yml, and Brett's testpypi and pypi approvals.
2. Right after that tag, create release/v1.1 at v1.1.0, and post it on docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473.
3. The v1.1.1 milestone's pull requests land on main from then on, under the merge words already given: lane 3's at 13:00:57Z and lane 4's at 19:09:44Z. Each is back-ported to release/v1.1.
4. v1.1.1 is tagged on release/v1.1 once the milestone is done there and the branch's tests pass on that commit.

One efficiency. While every PR landing on main belongs to the v1.1.1 milestone, release/v1.1 can follow main by fast-forward (or a merge of main), with no cherry-picks. Cherry-picks (git cherry-pick -x of the squash commit) are needed only once main also takes work meant for v1.2.0. Such work then goes on a v1.2.0 milestone, and only v1.1.1's commits are back-ported.

Work items

• tests.yml runs on pushes to release/v*. (tests.yml and release.yml: a push to a release/v<major>.<minor> branch that holds this change runs the suite as a push to main does, so a patch's commit there gets its push run with no dispatch, a fast-forward of that branch to main's commit no longer cancels main's run on it, and the release header says how a fix is back-ported (#850) #852, landed as 2c6543e8. release/v1.1's push runs prove it, the first being 39075754122 beside main's 39075632931 on 677f9bfa.) Today it runs on pushes to main only (on: push: branches: [main]). Every release-branch commit then gets the push run that release.yml's build job requires of the tagged commit; today one must be dispatched by hand. A commit that reaches release/v1.1 by fast-forward already has main's push run.

• The back-port procedure, in the RELEASING section of release.yml's header. (tests.yml and release.yml: a push to a release/v<major>.<minor> branch that holds this change runs the suite as a push to main does, so a patch's commit there gets its push run with no dispatch, a fast-forward of that branch to main's commit no longer cancels main's run on it, and the release header says how a fix is back-ported (#850) #852, landed as 2c6543e8.) That section is the repository's only written release procedure. (AGENTS.md is the product's guide for agents that use openRepoShape, and has no landing section.) The procedure says:

  • a release branch is cut at its vX.Y.0 tag;
  • a fix lands on main first;
  • it is back-ported by fast-forward while main holds only the patch's work, and otherwise by a PR to release/vX.Y with git cherry-pick -x <squash>;
  • a patch is tagged on release/vX.Y once that commit's push run is green.

  Step 1's "a release/v<X.Y> branch, which no push run tests" changes with the item above.

• A ruleset for release/*, made as brettheap. Done at 2026-10-18T01:06:33Z, on Brett Heap's word "go with option A for Release branching: main stays the trunk; release/vX.Y branches carry tagged releases and their patches; v1.1.1 back-ported to release/v1.1 #850" (2026-10-18T01:05:28Z): ruleset 25325536, "Release branches release/*: no force-push or deletion". It holds the rules deletion and non_fast_forward on refs/heads/release/*, with no bypass and no pull-request rule, so the fast-forward back-port stays. Before it, a release branch had only the all-branch non_fast_forward rule (ruleset 8981805), and its deletion was not blocked. GitHub cannot fast-forward a branch through a pull request, so a rule that every change goes through one rules out the fast-forward. The choice is between:

  • no force-push and no deletion, without a pull-request rule, so the fast-forward stays;
  • a pull-request rule, with every back-port a cherry-pick.

• The lanes' side, posted on docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473 (issuecomment-6244650070, 2026-10-18T02:20Z):

  • one HOLD at a time on release/v1.1;
  • the lane that landed a PR back-ports it, unless the release owner fast-forwards;
  • a LANDED line names both commits.

• Create release/v1.1 at the v1.1.0 tag, right after the tag. Done at 2026-10-17T21:57Z, at 190133d5.

• Open a v1.2.0 milestone for work that is not for v1.1.1. Done: milestone 5.

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code