Skip to content

docs(adr): record immutable semver tag decision; add release process; migrate internal @main refs - #44

Merged
cpitzi merged 2 commits into
mainfrom
agent/versioned-reusables-adr
Aug 16, 2026
Merged

docs(adr): record immutable semver tag decision; add release process; migrate internal @main refs#44
cpitzi merged 2 commits into
mainfrom
agent/versioned-reusables-adr

Conversation

@lentago-claude-runner

Copy link
Copy Markdown
Contributor

References #40.

Summary

Adds the ADR and release process for versioned reusable workflow consumption, and migrates the repo's own two internal @main references to @v1.0.0 as the first worked example.

ADR-0005 (docs/adr/0005-immutable-semver-tags-replace-main-consumption.md) records the decision made on #40:

  • Context: 16 repos, 50 references, one @main trust 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.
  • Decision: Immutable semver tags (@v1.0.0, @v1.1.0, …). Each release is a fixed point; a caller change requires an explicit, reviewable bump.
  • Explicitly rejected alternative: Moving major tag (@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.
  • Consequences: Releases no longer propagate for free; Dependabot (Fleet sweep: Dependabot on every repo (github-actions, npm, pip) .github#114 in flight) covers bumps as reviewable PRs where enrolled; @main continues 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.0 in claude-responder.yml and claude-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.

…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>
@cpitzi

cpitzi commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

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 required-checks.json stops matching, tightening permissions — is more useful than a generic semver link, because those are the failure modes callers actually hit.

One gap fixed on the branch. The reusables here call this repo's own composite action by its full external form pinned at @v1.0.0, which is required (inside a reusable workflow, a relative ./ path resolves against the caller's repo, not this one). The consequence is easy to miss: if those refs still read @v1.0.0 when v1.1.0 is tagged, the workflows inside v1.1.0 keep running the v1.0.0 action — a fix to the composite action ships to nobody even though a release went out. Added it as step 2 of the release process with the chicken-and-egg resolution (bump, merge, then tag that commit) and a grep to verify.

@cpitzi
cpitzi enabled auto-merge (squash) August 16, 2026 23:55
@cpitzi
cpitzi merged commit 98dbbd3 into main Aug 16, 2026
1 check passed
@cpitzi
cpitzi deleted the agent/versioned-reusables-adr branch August 16, 2026 23:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant