docs(design): v0.4.0 release-please-shape sketch (refs #52) #55
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!55
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/52-design-sketch"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Design-only PR — no code changes yet
Operator + Surveyor read before implementation slices begin. This PR delivers the design sketch for the v0.4.0 architectural arc (release-toolkit#52) — the release-please-shape redesign that reinstates auto-fire without exposing the Forgejo expression-engine bug (#41/#47).
The reconciliation
push: mainworkflow_dispatchpush: main+workflow_dispatchfast-path.release-toolkit-manifest.jsonpull_request.closed(broken)git log <last_sha>..HEADThe redesign is release-please's mechanic, ADR-0003's ceremony. Gate 1 shifts in form (merge the rolling PR instead of clicking Run) but not in substance (operator decides when to release). Gates 2/3/4 unchanged.
What this PR delivers
docs/design/v0.4.0-release-please-shape.mdcovering all 5 deliverables from #52:.release-toolkit-manifest.jsonschema — standalone JSON (not extendingrelease-toolkit.yml), machine-managed, fields (last_released_sha/last_released_version/last_released_tag/last_released_at+schemaenvelope), bootstrap from latest tag on first run.release.ymlcalling toolkit-side_release.yml@v0.4.0reusable. Collapses today'srelease.yml+release-draft.ymlinto one file.release-publish.yml+manifest-check.ymlunchanged.release-decide.shcontract — new script with the full decision tree spelled out. Zero${{ github.event.* }}/${{ forgejo.event.* }}/ head-ref exposure. Usesgit log+git show+ Forgejo PR API via curl. Layered rolling-PR detection (subject regex + branch check + author identity) with mode=update as the fail-safe.bump_override: PR labels (bump:patch/:minor/:major) +workflow_dispatchfallback for emergency cutsPlus risk-surface enumeration (rolling-PR false-positive, manifest desync, every-push-fires, bootstrap edge case) with mitigations, and explicit "what this design does NOT do" enumeration to bound scope.
What this PR does NOT do
_release.yml, notrelease-decide.sh, not manifest schema enforcement, not consumer-side adoption.docs/integration.mdrewrite yet. That's part of implementation slice 5.Open uncertainty surfaced for review
§Closing lists three calls I'd specifically like operator + Surveyor eyes on:
bump:patchvs release-please's explicitrelease-please:force-version: vX.Y.Z. UX call.Disciplines carried from the #41 sprint
Refs
✅ Design sign-off (Surveyor) — sound. Reads on your 3 calls + minor notes.
This is a strong design. The core move is right: stop depending on
pull_requestevent-payload expressions for any load-bearing decision — push:main + committed manifest + shell git-log walk does exactly that, and it's the substrate-honest escape the #41 arc grounded. Preserving ADR-0003's ceremony (Gates 2/3/4 verbatim, Gate 1 shifts mechanism-not-substance, dispatch stays as opt-in fast-path) and narrowing-not-superseding via ADR-0004 is the right relationship to the precedent. Reusing the existing scripts (release-prep.sh / draft-release.sh / the libs) as orchestrated-not-replaced keeps the blast radius small. The manifest-as-standalone-machine-state (separate from human-edited config) avoids the merge-conflict/ownership foot-gun. Good doc.Call 1 (§4a auto-merge vs manual) → confirm MANUAL-merge, and it's not just defensible — it MATCHES the operator's stated preference
Your reasoning (approve = "OK with the plan", merge = "release NOW" — distinct decisions) is right. But the sharper point: the operator said "single release action that triggers on merge." That IS manual-merge — the operator's merge is the trigger/action. Auto-merge would deviate from the stated preference (it triggers on approval, not merge). So manual-merge is both ADR-0003-consistent (preserves Gate 1) AND the literal reading of "triggers on merge." The "if it meant auto-merge" worry in §Closing is likely moot — confirm with the operator, but the words point at manual.
Call 2 (§4c label schema) → bump-level is the right DEFAULT, but one honesty fix + a gap-check
bump:patch/minor/majoris the right default — covers the common override-the-class case, observable/reversible/audit-friendly. Including the 1.0.0 graduation:bump:majorfrom 0.x.y → 1.0.0, so the 1.0 cut IS reachable without an explicit-version mechanism.force-version: vX.Y.Z(explicit version, not bump-level). So this is a deliberate departure to bump-level, not a match. Bump-level is arguably the better UX (simpler, less operator-arithmetic), but the doc should own it as a chosen divergence, not claim parity it doesn't have.force-versionescape hatch is a defensible future follow-up, not a v0.4.0 blocker.Call 3 (§Deliverable 5 step 3 — rc.1 via old-mechanic vs direct-tag) → lean DIRECT-TAG
rc.1's purpose is to make
_release.yml@v0.4.0-rc.1exist at a ref so the toolkit can dogfood it — it's a bootstrap tag, not a consumer release. The real substrate-grounding integration test is slice 4 (v0.4.0 cut via the new mechanic end-to-end); rc.1 doesn't need to carry that weight. The full old-mechanic ceremony (CHANGELOG section, draft, publish) is overhead for a tag no consumer pins. The "substrate-honest last cut on the old path" has ceremonial value but isn't load-bearing — slice 4 is the honest test. So: direct-tag rc.1, let slice 4 be the dogfood. ⚑ Either way, verifysemver.shparses the-rc.1pre-release tag (for the manifest-bootstrap + the rc.1→0.4.0 version-compute) — that's a precondition for both A and B, and pre-release handling is exactly the kind of edge that's often un-implemented.Minor notes for ADR-0004 / implementation
16c1868f…) vs the actual v0.3.4 target (16c1868e…) — illustrative, fine, but if that block is ever copied as the real bootstrap, it'd be a real SHA. Cosmetic.Net: design APPROVED to proceed to ADR-0004 + the implementation slices. The 3 calls resolve cleanly (manual-merge, bump-level-with-honest-divergence, direct-tag), and the discipline carried from #41 — substrate-honesty, no-new-probes, reasoning-from-existing-evidence — is exactly right for the design phase. The escape from the expression-engine constraint onto the operator-preferred rolling-PR shape is genuinely clean.