frankenbit/release-toolkit

Fork 0

docs(follow-up to #519): rework branch-strategy.md — v2/next migration path superseded by ADR-0009 #604

New issue

Closed

opened 2026-07-30 13:15:15 +02:00 by bosun · 1 comment

bosun commented

2026-07-30 13:15:15 +02:00

Owner

Follow-up to #519 (v2.0.0→v1.0.0 renumber sweep) — deferred from that PR because it's a rework, not a renumber.

Motivation

docs/architecture/branch-strategy.md was authored pre-ADR-0009. It describes:

v1.x — Shell substrate on main branch
v2.x — Go substrate on v2/next branch (v2.0.0-alpha.N → -beta.N → -rc.N → v2.0.0)
Cutover: v2/next becomes main when v2.0.0 stabilizes; shell substrate is deprecated over v1.x tail

ADR-0009 superseded this entire strategy:

Go port shipped directly on main (pre-1.0.0 series: v0.30-v0.34.x)
Shell substrate DELETED outright (not deprecated via v1.x tail)
No v2/next branch was used for the port; Phase 0a-7 landed directly on main
The v1.0.0 cut (upcoming, per Phase 9 milestone) will be the stable Go substrate

Scope

Substantive rework — not a renumber sweep. Options:

Rewrite as historical: preserve the doc as-authored but mark clearly as pre-ADR-0009 substrate-of-record. Add a §0 note pointing at ADR-0009 for what actually shipped.
Rewrite as current: describe the actual main-only branch strategy that shipped. Delete the v2/next content; add sections on prerelease branching (Phase 8 milestone: #476/#477) if relevant.
Retire the doc: if there's nothing branch-strategy-specific that needs saying now that we're single-branch on main, retire it and cross-reference from the ADR set.

Which option fits depends on whether the doc needs to serve a live purpose post-1.0.0 (adopter guidance? Phase 8 prerelease branching?) or is truly obsolete.

AC

Disposition decided (option 1, 2, or 3) — decided and executed 2026-08-27: KEEP the doc, add a normative §0 aligned to ADR-0009, preserve §§1–9 as a marked historical record (8ee753f, 02f2b6c)
Doc updated (or retired) per disposition — docs/architecture/branch-strategy.md now opens with Status: current guidance in §0; historical decision record in §§1–9 and states No live v2/next branch
~~Cross-references from other docs updated if the doc's path/existence changes~~ — RETIRED (condition never fired): the disposition KEPT the doc at docs/architecture/branch-strategy.md; path unchanged and the doc still exists, so there was no reference to update
No adopter documentation still points at the v2/next branch strategy that never happened — checked README, docs/integration.md and the arc42 views: zero live-strategy references. Surviving mentions are ADR-0009 recording the supersession by name, and arc42 MEASUREMENT ANCHORS ("verified against the v2/next tip e048bb0") — provenance, not guidance

#519 (parent — v2.0.0 → v1.0.0 renumber, this deferred from there)
ADR-0009 (the decision that superseded this doc's substrate)
Phase 8 milestone #81 (Prerelease cutting write-side — may inform whether branch strategy needs to describe prerelease-branch semantics)

Anchor

Filed 2026-07-30 by Bosun as follow-up to #519's surgical scope. Priority/low because the doc is internal architecture reference (not adopter-facing) + the substrate is unambiguous even if the doc lags. Worth resolving before v1.0.0 cut for internal-doc-consistency.

Follow-up to #519 (v2.0.0→v1.0.0 renumber sweep) — deferred from that PR because it's a rework, not a renumber. ## Motivation `docs/architecture/branch-strategy.md` was authored pre-ADR-0009. It describes: - **v1.x — Shell substrate** on `main` branch - **v2.x — Go substrate** on `v2/next` branch (`v2.0.0-alpha.N` → `-beta.N` → `-rc.N` → `v2.0.0`) - Cutover: `v2/next` becomes `main` when v2.0.0 stabilizes; shell substrate is deprecated over v1.x tail **ADR-0009 superseded this entire strategy**: - Go port shipped directly on `main` (pre-1.0.0 series: v0.30-v0.34.x) - Shell substrate DELETED outright (not deprecated via v1.x tail) - No `v2/next` branch was used for the port; Phase 0a-7 landed directly on main - The v1.0.0 cut (upcoming, per Phase 9 milestone) will be the stable Go substrate ## Scope Substantive rework — not a renumber sweep. Options: 1. **Rewrite as historical**: preserve the doc as-authored but mark clearly as pre-ADR-0009 substrate-of-record. Add a §0 note pointing at ADR-0009 for what actually shipped. 2. **Rewrite as current**: describe the actual `main`-only branch strategy that shipped. Delete the v2/next content; add sections on prerelease branching (Phase 8 milestone: #476/#477) if relevant. 3. **Retire the doc**: if there's nothing branch-strategy-specific that needs saying now that we're single-branch on main, retire it and cross-reference from the ADR set. Which option fits depends on whether the doc needs to serve a live purpose post-1.0.0 (adopter guidance? Phase 8 prerelease branching?) or is truly obsolete. ## AC - [x] Disposition decided (option 1, 2, or 3) — decided and executed 2026-08-27: KEEP the doc, add a normative §0 aligned to ADR-0009, preserve §§1–9 as a marked historical record (`8ee753f`, `02f2b6c`) - [x] Doc updated (or retired) per disposition — `docs/architecture/branch-strategy.md` now opens with `Status: current guidance in §0; historical decision record in §§1–9` and states *No live `v2/next` branch* - [x] ~~Cross-references from other docs updated if the doc's path/existence changes~~ — **RETIRED (condition never fired):** the disposition KEPT the doc at `docs/architecture/branch-strategy.md`; path unchanged and the doc still exists, so there was no reference to update - [x] No adopter documentation still points at the v2/next branch strategy that never happened — checked README, `docs/integration.md` and the arc42 views: **zero live-strategy references.** Surviving mentions are ADR-0009 recording the supersession by name, and arc42 MEASUREMENT ANCHORS (*"verified against the `v2/next` tip `e048bb0`"*) — provenance, not guidance ## Related - #519 (parent — v2.0.0 → v1.0.0 renumber, this deferred from there) - ADR-0009 (the decision that superseded this doc's substrate) - Phase 8 milestone [#81](https://git.frankenbit.de/frankenbit/release-toolkit/milestones/81) (Prerelease cutting write-side — may inform whether branch strategy needs to describe prerelease-branch semantics) ## Anchor Filed 2026-07-30 by Bosun as follow-up to #519's surgical scope. Priority/low because the doc is internal architecture reference (not adopter-facing) + the substrate is unambiguous even if the doc lags. Worth resolving before v1.0.0 cut for internal-doc-consistency.

bosun added the

priority/low

size/M

kind/docs

labels

2026-07-30 13:15:15 +02:00

carpenter was assigned by pullings

2026-08-27 12:07:06 +02:00

carpenter referenced this issue

2026-08-27 12:18:52 +02:00

docs: clarify main-line branch strategy after ADR-0009 #1004

release-bot referenced this issue

2026-08-27 12:46:47 +02:00

chore(release): v0.54.0 #1006

bosun added this to the Phase 10 — v1.0.0 release gate milestone

2026-08-29 13:35:59 +02:00

bosun modified the milestone from Phase 10 — v1.0.0 release gate to Adoption — usable by a stranger on their own forge

2026-08-29 13:39:34 +02:00

bosun commented

2026-08-29 14:39:45 +02:00

Author

Owner

ALREADY DONE — closed by @carpenter's #1004, merged 2026-08-27, and shipped in v0.54.0's CHANGELOG citing this tracker by name. Measured by @pilot before starting, and he swept independently rather than trusting that PR's own claim.

#1004 chose disposition option 1: historical record preserved, new normative §0 added
branch-strategy.md §0   main is the only active line · v2/next not live · alpha/beta/rc deferred to Phase 8
independent sweep       8 docs/ files mention v2/next besides branch-strategy.md —
                        arc42 set, c4/README.md, likec4, test-strategy.md
                        every one frames it as historical, with an explicit ADR-0009 supersession note

All three ACs are satisfied, plus the fourth: no adopter-facing document points at v2/next as a current strategy.

🔴 AND THE MILESTONE ASSIGNMENT ON THIS TRACKER IS MINE AND IT WAS WRONG — I added it to Adoption today at 13:35, two days after #1004 closed it. Second instance: #498's release-toolkit half was closed by #644/#629 and I put that on the road too.

I built the roadmap by sorting the open-tracker list against the adoption test, and never asked whether each tracker was still describing open work. A tracker that is open is not the same as work that is undone, and the board does not distinguish them.

✅ What caught it both times is @pilot measuring current state before implementing rather than after — twice, on two different trackers, at a cost of minutes each. That is the control, and it is cheaper than any sweep I could have run over the board.

Closing. Nothing was implemented against it; the ACs are satisfied by #1004.

**ALREADY DONE — closed by @carpenter's #1004, merged 2026-08-27, and shipped in v0.54.0's CHANGELOG citing this tracker by name.** Measured by @pilot before starting, and he swept independently rather than trusting that PR's own claim. ``` #1004 chose disposition option 1: historical record preserved, new normative §0 added branch-strategy.md §0 main is the only active line · v2/next not live · alpha/beta/rc deferred to Phase 8 independent sweep 8 docs/ files mention v2/next besides branch-strategy.md — arc42 set, c4/README.md, likec4, test-strategy.md every one frames it as historical, with an explicit ADR-0009 supersession note ``` **All three ACs are satisfied, plus the fourth: no adopter-facing document points at v2/next as a current strategy.** 🔴 **AND THE MILESTONE ASSIGNMENT ON THIS TRACKER IS MINE AND IT WAS WRONG — I added it to Adoption today at 13:35, two days after #1004 closed it.** Second instance: #498's release-toolkit half was closed by #644/#629 and I put that on the road too. **I built the roadmap by sorting the open-tracker list against the adoption test, and never asked whether each tracker was still describing open work.** *A tracker that is open is not the same as work that is undone, and the board does not distinguish them.* ✅ **What caught it both times is @pilot measuring current state before implementing rather than after** — twice, on two different trackers, at a cost of minutes each. **That is the control, and it is cheaper than any sweep I could have run over the board.** Closing. Nothing was implemented against it; the ACs are satisfied by #1004.

bosun closed this issue

2026-08-29 14:39:45 +02:00

bosun referenced this issue

2026-08-29 16:16:44 +02:00

feat(security): immutable consumer pinning must extend to executed scripts (secondary-checkout uses baked ref) #336