docs(adr): record immutable semver tag decision; add release process; migrate internal @main refs - #44
Conversation
…loses #40 partial) Adds ADR-0005 recording the decision to migrate from @main to immutable semver tags, with the explicitly-rejected moving-major-tag alternative and its consequences (bumps no longer propagate for free; Dependabot covers them where enrolled). Supersedes ADR-0002, whose status line is updated to reflect this. Adds RELEASING.md covering what must be green before tagging, the semver policy for reusable workflows, and how callers upgrade. Updates README.md versioning section to link the process doc and changes all four caller snippets to @v1.0.0. Updates CLAUDE.md to reflect the new posture. Migrates the repo's two internal @main references (render-claude-summary in claude-responder.yml and claude-review.yml) to @v1.0.0 as the first worked example. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
|
Reviewed. ADR discipline is exactly right — 0002 marked Superseded by 0005 with its original acceptance date preserved, 0005 marked Supersedes 0002, linked both ways, and the context is honest that 0002 deferred tagging rather than rejecting it. That's the difference between a reversal and a revision, and it reads correctly either direction years from now. RELEASING.md's semver policy is the part worth keeping: defining a breaking change for a reusable workflow specifically — removing an input, changing an existing default, renaming a job so One gap fixed on the branch. The reusables here call this repo's own composite action by its full external form pinned at |
References #40.
Summary
Adds the ADR and release process for versioned reusable workflow consumption, and migrates the repo's own two internal
@mainreferences to@v1.0.0as the first worked example.ADR-0005 (
docs/adr/0005-immutable-semver-tags-replace-main-consumption.md) records the decision made on #40:@maintrust point where a merge here changes every caller's CI instantly. The SHA-pinning wave (Fleet sweep: pin third-party actions to commit SHAs; pin container bases to digests .github#113) established that mutable refs are a supply-chain risk; consuming our own reusables through one would contradict that in the place a compromise reaches everything at once.@v1.0.0,@v1.1.0, …). Each release is a fixed point; a caller change requires an explicit, reviewable bump.@v1). A moving tag is mutable — repointing it silently changes all 16 repos at once. That is the same failure mode as@main, differing only in requiring a deliberate retag rather than a merge. Immutability is the whole point.@maincontinues working during migration (additive).ADR-0002 status updated to "Superseded by ADR-0005."
RELEASING.md covers the full release process: what must be green before tagging, the semver policy for reusable workflows specifically (what counts as a breaking change — removing/renaming an input, changing a default, changing which context a check reports, tightening permissions), how callers upgrade, and the
@main-is-unsupported rule.Docs updated: README.md versioning section replaced with a proper summary linking RELEASING.md; all four caller YAML snippets updated to
@v1.0.0; CLAUDE.md architecture section and gotchas updated to reflect the new posture.Internal ref migration:
render-claude-summary@main→@v1.0.0inclaude-responder.ymlandclaude-review.yml— the first migration and a worked example for fleet callers.Fleet caller migration (50 references across 16 repos) is staged separately per repo to avoid two writers on one workflow file — that work continues under #40.