TirSystem/github-action
0
1
Fork 0
Code Issues 5 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

Define the release process and version pinning

Browse Source 
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
This commit is contained in:
Tirsvad
2026-10-10 22:46:23 +08:00
parent aa18811003
commit 044d8ba21f
11 changed files with 513 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guides/release-process.md
+64
View File
@@ -0,0 +1,64 @@
# Release process
For the maintainers of this repository: how a change to the shared workflows
is validated, versioned and announced, and how consumers pin a version. The
decisions are in ADR-0006; this guide is the checklist. It is not published
on the wiki.
Until the release workflow exists (MIL-004 task 5) the steps are done by hand.
## What a version is
| Item | Rule |
| --- | --- |
| Unit | The whole repository: the workflows, their scripts and the guides |
| Version tag | `vMAJOR.MINOR.PATCH`, for example `v1.2.0`; never deleted or moved |
| Major tag | `vMAJOR`, for example `v1`; points to the latest compatible release |
| First release | `v1.0.0` |
| Breaking (new major) | A renamed or removed workflow, input, secret name or output; a raised default tool version or a changed default that can turn a green consumer red; a changed meaning of pass or fail |
| Minor | A new optional input, workflow or capability; nothing changes for existing callers |
| Patch | A fix, or documentation and tests, with no visible change for consumers |
## Checklist for a release
1. **Decide the version** from the table above, looking at every merged change
since the last tag.
2. **Check the commit.** The validation run (`validate-workflows`) on the exact
commit of `main` to be released is green; do not release from a red or
unchecked commit.
3. **Write the changelog entry** in `CHANGELOG.md`: the version, the date, and
the changes in the groups Breaking, Added, Changed and Fixed. A change that
touches credentials, tokens or permissions says so.
4. **Get the approval** of S01 for the release, in the pull request that adds
the changelog entry.
5. **Tag.** Create `vMAJOR.MINOR.PATCH` on the approved commit, then move
`vMAJOR` to it:
```bash
git tag -a v1.2.0 -m "v1.2.0" <commit>
git push origin v1.2.0
git tag -f v1 <commit> && git push -f origin v1
```
6. **Announce.** Create the release page for the tag with the changelog entry
as its text, and say whether consumers must act.
7. **Verify.** One repository pinned to the previous exact tag still runs the
same code; one repository on the major tag receives the release.
## How consumers pin
| Pin | Receives | Use when |
| --- | --- | --- |
| `@v1.2.0` | nothing new, ever | a pipeline must not change |
| `@v1` | compatible releases only | the default for a project |
| `@main` | everything, unreleased | never; only this repository's own tests |
Reusable workflows are pinned in the `uses:` line of the caller. The scoped
workflows (sync and publish wiki) are delivered from `main` by the instance
and cannot be pinned by a consumer; they fetch their scripts at the major tag
once `v1` exists.
## Undoing a faulty release
1. Move the major tag back to the previous exact tag:
`git tag -f v1 v1.1.0 && git push -f origin v1`.
2. Fix forward on `main` and release a patch version.
3. Do not delete or move an exact tag; consumers may have pinned it.