github-action/guides/release-process.md

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.

Steps 5 and 6 are done by the Release workflow (.gitea/workflows/release.yml, tools/release.py); the manual commands below are the fallback.

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: move the items of [Unreleased] under ## [x.y.z] - date in the groups Breaking, Added, Changed and Fixed. A change that touches credentials, tokens or permissions says so. Check it with python tools/changelog.py check --version x.y.z; a Breaking entry needs a new major version, and a new major version needs a Breaking entry.

4. Get the approval of S01 for the release, in the pull request that adds the changelog entry.

5. Run the Release workflow in dry-run mode. In the Actions tab of this repository start Release on main with the version and dry_run true. It checks that the commit is the tip of main, that its validation run is green, that the changelog has an entry for the version and that the tag does not exist, and writes nothing.

6. Release. Start Release again with dry_run false. It creates the tag vMAJOR.MINOR.PATCH, the release page with the text of python tools/changelog.py notes x.y.z, and moves vMAJOR to the commit when this is the highest version of its major. The page on Gitea is the only destination (ADR-0007); nothing is attached to it. The workflow uses the token of its own run; if Gitea refuses it, store TOKEN_FOR_GITEA_RELEASE as a secret with write access to this repository only.

   By hand, the same steps are:

   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
   

   and create the release page with the notes of the changelog entry.

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.