Defines the release process and version pinning (MIL-004 task 1, issue #20). Documents only; nothing is released and no workflow changes.
Use case first
UC-006 (brief): Release a Reusable Workflow, primary actor DevOps Professional (S05).
UCD-001: the use case added. US-001: US-001.11 (only validated commits are released), US-001.12 (a release says whether it is breaking), US-001.13 (a pin that does not move; traced to the MIL-004 epic because it is a consumer's goal).
The decision (ADR-0006)
The repository is released as a whole with a semantic version tag vMAJOR.MINOR.PATCH and a moving major tag vMAJOR that points to the latest compatible release. Consumers pin @vMAJOR or an exact tag and never @main.
A release is cut from main only when the validation run of that exact commit is green and CHANGELOG.md has an entry for the version that marks each breaking change; it is announced by a release page generated from that entry.
Breaking (new major): a renamed or removed workflow, input, secret name or output; a raised default tool version or changed default that can turn a green consumer red; a changed meaning of pass or fail. First release v1.0.0.
Exact tags are never deleted or moved; the major tag may move back to the previous exact tag when a release proves faulty.
Once v1 exists the scoped workflows fetch their scripts at ref: v1 instead of main.
A limitation the ADR states plainly: a scoped workflow file is delivered from main by the instance and cannot be pinned by a consumer, so a bad merge of sync-github-metadata.yml or publish-wiki.yml still reaches every repository. Review of main is the only protection for those two files.
Guide
guides/release-process.md is a seven-step maintainers' checklist. It is deliberately not on the wiki.
Review (S01 standing in as ADR-0002 records; no independent reader)
RC-040 UCD-001 and RC-042 UC-006 pass; RC-041 US-001 passes after one fix (US-001.13 traced to the epic); RC-043 ADR-0006 passes after one fix (SemVer expanded). Action items: S05 to pin the scripts to v1 once it exists (2026-11-28); S01 to review who may merge to main and move tags (2026-11-14).
Defines the release process and version pinning (MIL-004 task 1, issue #20). Documents only; nothing is released and no workflow changes.
## Use case first
- **UC-006** (brief): Release a Reusable Workflow, primary actor DevOps Professional (S05).
- **UCD-001**: the use case added. **US-001**: US-001.11 (only validated commits are released), US-001.12 (a release says whether it is breaking), US-001.13 (a pin that does not move; traced to the MIL-004 epic because it is a consumer's goal).
## The decision (ADR-0006)
- The repository is released as a whole with a semantic version tag `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR` that points to the latest compatible release. Consumers pin `@vMAJOR` or an exact tag and never `@main`.
- A release is cut from `main` only when the validation run of that exact commit is green and `CHANGELOG.md` has an entry for the version that marks each breaking change; it is announced by a release page generated from that entry.
- Breaking (new major): a renamed or removed workflow, input, secret name or output; a raised default tool version or changed default that can turn a green consumer red; a changed meaning of pass or fail. First release `v1.0.0`.
- Exact tags are never deleted or moved; the major tag may move back to the previous exact tag when a release proves faulty.
- Once `v1` exists the scoped workflows fetch their scripts at `ref: v1` instead of `main`.
**A limitation the ADR states plainly:** a scoped workflow file is delivered from `main` by the instance and cannot be pinned by a consumer, so a bad merge of `sync-github-metadata.yml` or `publish-wiki.yml` still reaches every repository. Review of `main` is the only protection for those two files.
## Guide
`guides/release-process.md` is a seven-step maintainers' checklist. It is deliberately not on the wiki.
## Review (S01 standing in as ADR-0002 records; no independent reader)
RC-040 UCD-001 and RC-042 UC-006 pass; RC-041 US-001 passes after one fix (US-001.13 traced to the epic); RC-043 ADR-0006 passes after one fix (SemVer expanded). Action items: S05 to pin the scripts to `v1` once it exists (2026-11-28); S01 to review who may merge to `main` and move tags (2026-11-14).
Closes #20
Add the brief use case UC-006 (Release a Reusable Workflow), the use case in
UCD-001, stories US-001.11 to US-001.13 and ADR-0006: one version for the
repository with SemVer tags and a moving major tag, a release only from a
green commit with a changelog entry, consumers pin the major or an exact tag
and never main. Add the maintainers' checklist guides/release-process.md.
Review and accept them (RC-040 to RC-043), update TM-001 and the registry.
Task: MIL-004#1
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Defines the release process and version pinning (MIL-004 task 1, issue #20). Documents only; nothing is released and no workflow changes.
Use case first
The decision (ADR-0006)
vMAJOR.MINOR.PATCHand a moving major tagvMAJORthat points to the latest compatible release. Consumers pin@vMAJORor an exact tag and never@main.mainonly when the validation run of that exact commit is green andCHANGELOG.mdhas an entry for the version that marks each breaking change; it is announced by a release page generated from that entry.v1.0.0.v1exists the scoped workflows fetch their scripts atref: v1instead ofmain.A limitation the ADR states plainly: a scoped workflow file is delivered from
mainby the instance and cannot be pinned by a consumer, so a bad merge ofsync-github-metadata.ymlorpublish-wiki.ymlstill reaches every repository. Review ofmainis the only protection for those two files.Guide
guides/release-process.mdis a seven-step maintainers' checklist. It is deliberately not on the wiki.Review (S01 standing in as ADR-0002 records; no independent reader)
RC-040 UCD-001 and RC-042 UC-006 pass; RC-041 US-001 passes after one fix (US-001.13 traced to the epic); RC-043 ADR-0006 passes after one fix (SemVer expanded). Action items: S05 to pin the scripts to
v1once it exists (2026-11-28); S01 to review who may merge tomainand move tags (2026-11-14).Closes #20