decision: thoroughly investigate cost/benefit of replacing release-toolkit's notes-generation lib with RNA backend (ADR-0006 deferred-decision re-engagement) #98

New issue

Closed

opened 2026-06-26 11:36:05 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-26 11:36:05 +02:00

Owner

Operator directive

Per operator decision 2026-06-26: after the upcoming v0.6.2 cut lands, re-engage the deferred ADR-0006 decision with a thorough cost/benefit investigation of replacing part of release-toolkit's internal notes-generation with RNA (release-notes-assistant) as an external backend.

Verbatim operator framing: "Let us reconsider this after the upcoming cut and investigate thoroughly the costs and benefits, if we would replace a part of release-toolkit with RNA."

Current state (recap from the deferral)

ADR-0006: Status: proposed (decision deferred to post-v0.4.0 cut). The "re-ask the operator post-v0.4.0" line item never fired.
(B1) fragment frontmatter summary: (#77, shipped v0.5.0): "lighter sibling of (a3)" — bifurcates prose (sidecar short / CHANGELOG long) WITHOUT bifurcating lifecycle. Absorbed the immediate operator pain (release page rendering).
The broader question — should release-toolkit replace lib/conventional-commits.sh + lib/fragments.sh + parts of lib/changelog.sh with RNA as an external backend? — never received a formal answer.

(B1) has shipped through 4 cuts (v0.5.0 / v0.6.0 / v0.6.1 / v0.6.2) without operator flagging a missing-(a3) pain. This investigation should empirically test whether the gap is real before committing to architectural change.

Investigation scope (post-v0.6.2)

Costs to enumerate

Implementation effort: replace which lib helpers, how much refactor, what shim layers required
Migration burden on consumers: cellblock (#420) + tmux-tell (#421) are mid-adoption; what breaks for them
Vendor coupling risk: RNA is Forgejo-team-owned; tracks their roadmap. What if their design choices diverge from our needs (e.g., they pin to a categorization scheme we don't share)?
Learning curve: RNA's --categorize script convention vs our file-name-suffix convention
Maintenance: who maintains the integration layer; how breakage in RNA cascades
Loss of self-containment: release-toolkit currently has zero external runtime dependencies for its core logic; adding RNA changes that
Substrate-state-care exposure (AGENTS.md §8 Axis A): RNA is an external system; every claim we make about its behavior would need lifecycle-state verification per the n=4 promoted pattern

Benefits to enumerate

Iterative edit-preservation on release notes: RNA preserves operator edits between  markers across runs. We currently consume-and-delete fragments at cut (one-shot). For consumers who want to edit release notes post-prep + have those edits respected across re-cuts, RNA gives this for free.
Leverage Forgejo team's ongoing work: RNA's categorization, custom --categorize script support, milestone-mode, PR-preview rendering — features we'd otherwise need to build.
Reduce maintenance burden of release-toolkit's internal notes-generation libs
Cleaner architectural primitive: per-artifact lifecycle separation (release notes ≠ CHANGELOG) becomes first-class rather than per-fragment-field via (B1)
Substrate-honest composition: matches Forgejo team's "release notes are not changelogs" documented position

Empirical data to gather (NEW since deferral)

What did (B1) NOT solve? 4 cuts of evidence — any operator pain that points at (a3)-shaped gaps?
What did v0.4.0+ surface about the lib helpers we'd replace? The carry-forward catches (#66/#70/#73/#78/#86/#87/#92/#56/#54) — would any of them have been simpler/avoidable if RNA owned the categorization layer?
Cellblock + tmux-tell adoption experience: have they hit edge cases the lib helpers handled poorly, or has the path been smooth?
RNA's own maturity: check their recent commit cadence + release cadence; is it a stable substrate to integrate against?

Comparison axes

Status quo (B1 + internal libs) — current default
(c) — don't integrate — formalize the status-quo as the decision
(a3) — RNA for release-notes scope — what operator's original phrasing reads as
(a1)/(a2) — broader RNA integration — would require fresh design enumeration
(b) — release-toolkit-side iterative-edit feature — alternative path that doesn't require RNA

Decision artifacts

This issue should produce:

Updated ADR-0006 — status flipped from proposed (deferred) to decided: <chosen path> with empirical rationale
Implementation roadmap if the decision is (a3) or other-than-status-quo
Migration plan for cellblock + tmux-tell if needed
Closure note for the deferred-decision item so future sessions don't re-open the question without evidence-of-change

Sequencing

Strictly post-v0.6.2 GA:

v0.6.2 GA must ship cleanly first (currently in flight — PR #97 awaiting Surveyor review)
The substrate-correction cycle should settle (i.e., v0.6.2 cut surfaces no new substrate catch, OR the catch is well-scoped) before introducing architectural-change consideration
v0.6.3+ sprint slot for the actual investigation work + ADR-0006 update PR

If v0.6.2 cut DOES surface a new substrate catch, the carry-forward-cycle priority preempts this investigation — fix that first.

Refs

ADR-0006: docs/adr/0006-rna-integration-design-note.md (status: proposed, deferred)
(B1) implementation: #77 — fragment frontmatter (B1) absorbed immediate need; ADR-0006 broader scope still open
RNA upstream: release-notes-assistant (Forgejo team's tool)
Operator framing: 2026-06-26 directive ("Let us reconsider this after the upcoming cut and investigate thoroughly the costs and benefits")
Sister architectural axes: AGENTS.md §8 Axis A (external-system-claim discipline applies to RNA integration), Axis C (trusted-proxy at report layer if RNA exposes status APIs we'd consume)

## Operator directive Per operator decision 2026-06-26: **after the upcoming v0.6.2 cut lands**, re-engage the deferred ADR-0006 decision with a **thorough cost/benefit investigation** of replacing part of release-toolkit's internal notes-generation with RNA ([release-notes-assistant](https://code.forgejo.org/forgejo/release-notes-assistant)) as an external backend. Verbatim operator framing: *"Let us reconsider this after the upcoming cut and investigate thoroughly the costs and benefits, if we would replace a part of release-toolkit with RNA."* ## Current state (recap from the deferral) - **[ADR-0006](docs/adr/0006-rna-integration-design-note.md)**: `Status: proposed (decision deferred to post-v0.4.0 cut)`. The "re-ask the operator post-v0.4.0" line item never fired. - **(B1) fragment frontmatter `summary:`** ([#77](https://git.frankenbit.de/frankenbit/release-toolkit/issues/77), shipped v0.5.0): "lighter sibling of (a3)" — bifurcates prose (sidecar short / CHANGELOG long) WITHOUT bifurcating lifecycle. Absorbed the immediate operator pain (release page rendering). - **The broader question — should release-toolkit replace `lib/conventional-commits.sh` + `lib/fragments.sh` + parts of `lib/changelog.sh` with RNA as an external backend? — never received a formal answer.** (B1) has shipped through 4 cuts (v0.5.0 / v0.6.0 / v0.6.1 / v0.6.2) without operator flagging a missing-(a3) pain. This investigation should empirically test whether the gap is real before committing to architectural change. ## Investigation scope (post-v0.6.2) ### Costs to enumerate - **Implementation effort**: replace which lib helpers, how much refactor, what shim layers required - **Migration burden on consumers**: cellblock ([#420](https://git.frankenbit.de/frankenbit/release-toolkit/issues/420)) + tmux-tell ([#421](https://git.frankenbit.de/frankenbit/release-toolkit/issues/421)) are mid-adoption; what breaks for them - **Vendor coupling risk**: RNA is Forgejo-team-owned; tracks their roadmap. What if their design choices diverge from our needs (e.g., they pin to a categorization scheme we don't share)? - **Learning curve**: RNA's `--categorize` script convention vs our file-name-suffix convention - **Maintenance**: who maintains the integration layer; how breakage in RNA cascades - **Loss of self-containment**: release-toolkit currently has zero external runtime dependencies for its core logic; adding RNA changes that - **Substrate-state-care exposure (AGENTS.md §8 Axis A)**: RNA is an external system; every claim we make about its behavior would need lifecycle-state verification per the n=4 promoted pattern ### Benefits to enumerate - **Iterative edit-preservation on release notes**: RNA preserves operator edits between `` markers across runs. We currently consume-and-delete fragments at cut (one-shot). For consumers who want to edit release notes post-prep + have those edits respected across re-cuts, RNA gives this for free. - **Leverage Forgejo team's ongoing work**: RNA's categorization, custom `--categorize` script support, milestone-mode, PR-preview rendering — features we'd otherwise need to build. - **Reduce maintenance burden** of release-toolkit's internal notes-generation libs - **Cleaner architectural primitive**: per-artifact lifecycle separation (release notes ≠ CHANGELOG) becomes first-class rather than per-fragment-field via (B1) - **Substrate-honest composition**: matches Forgejo team's "release notes are not changelogs" documented position ### Empirical data to gather (NEW since deferral) - **What did (B1) NOT solve?** 4 cuts of evidence — any operator pain that points at (a3)-shaped gaps? - **What did v0.4.0+ surface about the lib helpers we'd replace?** The carry-forward catches (#66/#70/#73/#78/#86/#87/#92/#56/#54) — would any of them have been simpler/avoidable if RNA owned the categorization layer? - **Cellblock + tmux-tell adoption experience**: have they hit edge cases the lib helpers handled poorly, or has the path been smooth? - **RNA's own maturity**: check their recent commit cadence + release cadence; is it a stable substrate to integrate against? ### Comparison axes - **Status quo (B1 + internal libs)** — current default - **(c) — don't integrate** — formalize the status-quo as the decision - **(a3) — RNA for release-notes scope** — what operator's original phrasing reads as - **(a1)/(a2) — broader RNA integration** — would require fresh design enumeration - **(b) — release-toolkit-side iterative-edit feature** — alternative path that doesn't require RNA ### Decision artifacts This issue should produce: 1. **Updated ADR-0006** — status flipped from `proposed (deferred)` to `decided: <chosen path>` with empirical rationale 2. **Implementation roadmap** if the decision is (a3) or other-than-status-quo 3. **Migration plan for cellblock + tmux-tell** if needed 4. **Closure note for the deferred-decision item** so future sessions don't re-open the question without evidence-of-change ## Sequencing **Strictly post-v0.6.2 GA**: - v0.6.2 GA must ship cleanly first (currently in flight — PR #97 awaiting Surveyor review) - The substrate-correction cycle should settle (i.e., v0.6.2 cut surfaces no new substrate catch, OR the catch is well-scoped) before introducing architectural-change consideration - v0.6.3+ sprint slot for the actual investigation work + ADR-0006 update PR If v0.6.2 cut DOES surface a new substrate catch, the carry-forward-cycle priority preempts this investigation — fix that first. ## Refs - **ADR-0006**: [docs/adr/0006-rna-integration-design-note.md](docs/adr/0006-rna-integration-design-note.md) (status: proposed, deferred) - **(B1) implementation**: [#77](https://git.frankenbit.de/frankenbit/release-toolkit/issues/77) — fragment frontmatter (B1) absorbed immediate need; ADR-0006 broader scope still open - **RNA upstream**: [release-notes-assistant](https://code.forgejo.org/forgejo/release-notes-assistant) (Forgejo team's tool) - **Operator framing**: 2026-06-26 directive ("Let us reconsider this after the upcoming cut and investigate thoroughly the costs and benefits") - **Sister architectural axes**: AGENTS.md §8 Axis A (external-system-claim discipline applies to RNA integration), Axis C (trusted-proxy at report layer if RNA exposes status APIs we'd consume)

quartermaster referenced this issue

2026-06-26 12:00:49 +02:00

docs: AGENTS.md §10 — substrate-grounding arc converged at v0.6.2 #102

quartermaster referenced this issue from a commit

2026-06-26 13:43:22 +02:00

docs(adr-0006): decided — option (c) don't integrate RNA as backend (closes #98)

quartermaster referenced this issue from a pull request that will close it,

2026-06-26 13:43:55 +02:00

docs(adr-0006): decided — option (c) don't integrate RNA as backend (closes #98) #104

quartermaster referenced this issue from a commit

2026-06-26 13:53:39 +02:00

docs(adr-0006): decided — option (c) don't integrate RNA as backend (closes #98)