admin/cozystack

0 Fork 0

mirror of https://github.com/cozystack/cozystack.git synced 2026-11-09 22:13:18 +09:00

Files

T

Myasnikov Daniil 35a4f7c5d9 docs(release): split the release document into one page per topic

docs/release.md had grown into one page that mixed the release model,
the CI pipeline, changelogs, signatures, nightlies and the fires seen
at release time. A reader looking for one of them read all of it, and
an edit to one part reflowed the rest. It now indexes one page per
topic under docs/release/.

The pages already describe how fixes reach a release line through the
backport batch, which the following commits add. Workflows, scripts
and tests that named docs/release.md now point at the page that holds
the text they mean.

Assisted-By: LLM
Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>

2026-11-04 15:03:06 +00:00

5.4 KiB

Raw Blame History

Release Workflow

The release documentation is both the process design (what the release model looks like) and the operational playbook (what to actually do, what breaks, what to verify), split into one page per topic under release/. Companion to agents/changelog.md, which is the canonical changelog process.

When to use this guide

You are about to:

Cut a pre-release (vX.Y.0-rc.N, or vX.Y.0-alpha.N / -beta.N).
Cut a regular release (vX.Y.0).
Cut a patch release (vX.Y.Z with Z > 0).
Triage cherry-picks before a patch release.
Investigate why CI is misbehaving on a tag push.
Review a promote (release) PR.

If you are about to generate a changelog only, jump straight to agents/changelog.md.

Pages

Introduction: the three release types and the tag push that drives the pipeline.
Release Candidates: what an rc is, and how cutting the first one freezes release-X.Y.
Regular Releases: promoting an rc to vX.Y.0, step by step.
Patch Releases: the same flow for vX.Y.Z on an existing release-X.Y line.
What CI does during the release process: which workflow does what, phase by phase, including multi-arch builds and the rc E2E gate.
Stable tags come from rc promotion: why a stable tag only ever comes from promoting an rc.
Release signatures and SBOM: the source SBOM, checksums and cosign signature on each release, the SBOM each release image carries, and how to verify and read them.
Nightly builds: how a nightly mirrors main to GHCR, and how to install one.
Backports: the policy that decides what goes into a patch release, and how a contributor gets a fix there.
Backport mechanics: cherry-pick triage before a patch, and the monotonic-counter trap.
Backport tasks: resolving a batch conflict, deferring the original a failed batch CI comes from, and checking a pull request title, with the check each has to pass.
Changelogs: changelog failure modes and the pre-publish checks.
Release-time fires: regressions that escaped to users, and the verification gaps they expose.
Pre-release verification checklist: what to verify before merging a release PR.
CI failures release engineers commonly hit: known failures and whether each one blocks a release.
Tag immutability: write-once tags and the rulesets that enforce them.
Splitting a release-blocking bundle PR: how to break up a grab-bag PR that blocks a release.
Cleanup after release: what is left to clean up once a release is out.

See also

agents/changelog.md — canonical changelog generation process.
agents/contributing.md — commit/PR conventions.
agents/releasing.md — pointer file for AI agents handling release tasks.
.github/workflows/cut-prerelease.yaml — the sole entry point for cutting a pre-release tag as the CI app.
.github/workflows/tags.yaml — tag-push pipeline (rc build + mandatory rc-e2e; stable-tag changelog/website backstops).
.github/workflows/e2e-tag.yaml — mandatory rc and manual published-tag full E2E lane.
.github/workflows/pull-requests-release.yaml — merge-finalize pipeline.
.github/workflows/promote-rc.yaml — rc → stable promotion.
.github/workflows/changelog-rc.yaml — optional rc-time changelog button.
.github/workflows/changelog-generate.yaml — reusable changelog-generation core shared by promote-rc and changelog-rc.
.github/workflows/nightly.yaml — nightly: mirror main OCIR→GHCR + full e2e.
hack/nightly-mirror.sh — cross-registry image mirror used by the nightly.
agents/image-refs.md — where image references live, what their tags mean, and the invariants promotion and mirroring rely on.
hack/lib/image-refs.sh — the single enumeration of ref-bearing files, shared by the promote, retag and mirror tooling.
.github/workflows/retention.yaml — GHCR nightly and abandoned promotion-candidate pruning.
cmd/backport-batch — the backport batch that applies the backport policy.
.github/workflows/backport-batch.yaml — runs the backport batch on Monday and Thursday for each line it runs for: the newest released lines, and a line in its rc window.
.github/workflows/update-releasenotes.yaml — sync changelog → GitHub Release body.