Skip to content

Commit e95a460

Browse files
docs(release): document the rc freeze
The Release Candidates section said the opposite of current behaviour — "new features and changes can still be added before the regular release" — so it is rewritten around the freeze, along with the Regular Release step list, both gitGraph diagrams, and the workflow reference sections. The promote PR now targets release-X.Y rather than main, so the diagrams show main forking away at the freeze and never receiving the release commit. Patch Releases collapses to "same as above, the branch already exists", since after the freeze both flows are identical. Assisted-By: Claude <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent b929799 commit e95a460

1 file changed

Lines changed: 52 additions & 29 deletions

File tree

‎docs/release.md‎

Lines changed: 52 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,19 @@ All three are matched by `tags.yaml`'s regex `^v\d+\.\d+\.\d+(-(alpha|beta|rc)\.
2929

3030
## Release Candidates
3131

32-
Release candidates are Cozystack versions that introduce new features and are published before a stable release.
33-
Their purpose is to help validate stability before finalizing a new feature release.
34-
They allow for final rounds of testing and bug fixes without freezing development.
32+
Release candidates are Cozystack versions that introduce new features and are published before a stable release. Their purpose is to help validate stability before finalizing a new feature release.
3533

36-
Release candidates are given numbers `vX.Y.0-rc.N`, for example, `v1.2.0-rc.1`.
37-
They are created directly in the `main` branch.
38-
An RC is typically tagged when all major features for the upcoming release have been merged into main and the release enters its testing phase.
39-
However, new features and changes can still be added before the regular release `vX.Y.0`.
34+
Release candidates are given numbers `vX.Y.0-rc.N`, for example, `v1.2.0-rc.1`. The first one is cut from `main`, once all major features for the upcoming release have merged and the release enters its testing phase.
4035

41-
Each RC contributes to a cumulative set of release notes that will be finalized when `vX.Y.0` is released.
42-
After testing, if no critical issues remain, the regular release (`vX.Y.0`) is tagged from the last RC or a later commit in main.
43-
This begins the regular release process, creates a dedicated `release-X.Y` branch, and opens the way for patch releases.
36+
**Cutting the first rc freezes the line.** [`cut-prerelease.yaml`](../.github/workflows/cut-prerelease.yaml) creates `release-X.Y` at the tagged commit, and from that point the release's content is closed:
37+
38+
- Every later cut for that line — `rc.2`, `rc.3`, an `alpha`/`beta`, or a patch-line rc — must be dispatched from `release-X.Y`. A dispatch from `main` is refused.
39+
- Fixes reach the release only by cherry-pick or backport onto `release-X.Y` (see [Backporting](#backporting)).
40+
- `main` reopens immediately for the next minor, so feature work never has to wait for the release to ship.
41+
42+
This is what makes an rc mean something. Previously `release-X.Y` was created only when the stable release merged, so `rc.2` was cut from `main`'s tip and silently absorbed everything that had landed since `rc.1` — the shipped release could contain code that no rc had ever validated.
43+
44+
Each RC contributes to a cumulative set of release notes that will be finalized when `vX.Y.0` is released. After testing, if no critical issues remain, the last green rc is promoted to `vX.Y.0` — the same bytes, retagged, never rebuilt.
4445

4546
## Regular Releases
4647

@@ -55,52 +56,74 @@ gitGraph
5556

5657
A regular release sequence runs as follows:
5758

58-
1. Cut a release candidate (`v1.2.0-rc.N`) from the last good commit on `main`: run the [`Cut Pre-release Tag`](../.github/workflows/cut-prerelease.yaml) workflow (manual dispatch **from `main`**) with the tag. It tags `main`'s HEAD as the CI app; `tags.yaml` then builds the rc images, drafts the rc release, and pushes the digest-vendored `release-1.2.0-rc.N` staging branch.
59-
2. Validate the rc. New features and fixes can still land on `main` and be picked up by a later rc.
59+
1. Cut the first release candidate (`v1.2.0-rc.1`) from the last good commit on `main`: run the [`Cut Pre-release Tag`](../.github/workflows/cut-prerelease.yaml) workflow (manual dispatch **from `main`**) with the tag. It tags `main`'s HEAD as the CI app, then **creates `release-1.2` at that commit, freezing the line**; `tags.yaml` builds the rc images, drafts the rc release, and pushes the digest-vendored `release-1.2.0-rc.N` staging branch.
60+
2. Validate the rc. `main` is already open for the next minor, so anything landing there is **not** in this release. Fixes for `1.2` are cherry-picked onto `release-1.2`, and a later rc is cut by dispatching the workflow **from `release-1.2`**.
61+
62+
```mermaid
63+
gitGraph
64+
commit id: "feature"
65+
commit id: "feature 2"
66+
commit id: "feature 3" tag: "v1.2.0-rc.1"
67+
branch release-1.2
68+
checkout main
69+
commit id: "feature 4 (next minor)"
70+
checkout release-1.2
71+
commit id: "cherry-picked fix" tag: "v1.2.0-rc.2"
72+
```
73+
6074
3. Once an rc is green, run the [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) workflow (manual dispatch) with that rc tag. Promotion is **transactional** — it performs no registry mutation at dispatch. It:
6175
1. Pushes the `release-1.2.0` branch: the rc's digest-vendored tree with the rc version substring rewritten to `1.2.0` (the digests are the rc's — unchanged).
6276
2. Drafts the `v1.2.0` release and uploads the (restamped) assets.
63-
3. Opens the `chore(release): promote v1.2.0-rc.N -> v1.2.0` PR into `main`, labelled `release` and `full-e2e` (the latter forces the full e2e suite on the PR). The retag itself is deferred to the merge (step 5) — so an abandoned promotion leaves no stable-named images and cannot wedge a re-promotion.
77+
3. Opens the `chore(release): promote v1.2.0-rc.N -> v1.2.0` PR into `release-1.2`, labelled `release` and `full-e2e` (the latter forces the full e2e suite on the PR). The retag itself is deferred to the merge (step 5) — so an abandoned promotion leaves no stable-named images and cannot wedge a re-promotion.
78+
79+
The PR targets the maintenance branch, not `main`: `promote-rc.yaml` prefers `release-X.Y` whenever it exists, and since the rc freeze it always does. The digest-vendored `Prepare release` commit therefore stays on the release line instead of landing on `main`.
6480

6581
```mermaid
6682
gitGraph
67-
commit id: "feature"
68-
commit id: "feature 2"
6983
commit id: "feature 3" tag: "v1.2.0-rc.1"
84+
branch release-1.2
85+
checkout release-1.2
86+
commit id: "cherry-picked fix" tag: "v1.2.0-rc.2"
7087
branch release-1.2.0
7188
checkout release-1.2.0
7289
commit id: "Prepare release v1.2.0"
73-
checkout main
90+
checkout release-1.2
7491
merge release-1.2.0 id: "Pull Request"
7592
```
7693

7794
4. Maintainer reviews the PR and the draft release, then merges it — **do not squash-merge**, the stable tag must attach to a real merge commit. GitHub removes the merged branch `release-1.2.0` (the repo has auto-delete-on-merge enabled).
7895
5. CI workflow triggers on merge (this is where every irreversible side effect happens, all after the PR's e2e passed):
7996
1. Creates the tag `v1.2.0` at the newly created merge commit — write-once. The tag is published here for the first time, never moved.
8097
2. Cuts the write-once `api/apps/v1alpha1/v1.2.0` Go-module tag at the same commit.
81-
3. Ensures the `release-1.2` maintenance branch exists at the tag commit.
98+
3. Ensures the `release-1.2` maintenance branch exists at the tag commit. Since the rc freeze created it, this is normally a no-op fast-forward: the merge commit is already its tip.
8299
4. Publishes the release page (`draft` → `latest`).
83100
5. Retags the rc's images by digest to `v1.2.0` (and `:latest` only when `v1.2.0` is the newest published stable), and publishes the stable `cozy-installer` chart — no rebuild.
84101
6. The maintainer can now announce the release to the community.
85102

86103
```mermaid
87104
gitGraph
88-
commit id: "feature"
89105
commit id: "feature 2"
90106
commit id: "feature 3" tag: "v1.2.0-rc.1"
107+
branch release-1.2
108+
checkout main
109+
commit id: "feature 4 (next minor)"
110+
checkout release-1.2
111+
commit id: "cherry-picked fix" tag: "v1.2.0-rc.2"
91112
branch release-1.2.0
92113
checkout release-1.2.0
93114
commit id: "Prepare release v1.2.0"
94-
checkout main
115+
checkout release-1.2
95116
merge release-1.2.0 id: "Release v1.2.0" tag: "v1.2.0"
96117
```
97118

119+
Note that `main` never receives the release commit. It forked away at the freeze and carries the next minor's work.
120+
98121
## Patch Releases
99122

100-
Making a patch release has a lot in common with a regular release, with a couple of differences:
123+
A patch release now follows exactly the same shape as the regular release above — by the time `vX.Y.0` ships, everything is already happening on `release-X.Y`. The only difference is where the line starts:
101124

102-
* The rc and its promotion happen on the `release-X.Y` maintenance branch instead of `main`.
103-
* Patch commits are cherry-picked to that branch before the rc is tagged.
125+
* `release-X.Y` already exists, created by the freeze at `vX.Y.0-rc.1`, so there is no branch to create.
126+
* Patch commits are cherry-picked onto it, and the rc is cut by dispatching **from `release-X.Y`** — the same dispatch used for `rc.2` of the original release.
104127

105128

106129
Let's assume that we've released `v1.2.0` and that development is ongoing.
@@ -120,11 +143,11 @@ gitGraph
120143
```
121144

122145

123-
1. The maintainer creates a release branch, `release-1.2,` and cherry-picks patch commits from `main` to `release-1.2`.
124-
These must be only patches to features that were present in version `v1.2.0`.
146+
1. The maintainer cherry-picks patch commits from `main` onto the existing `release-1.2` branch. These must be only patches to features that were present in version `v1.2.0`.
147+
148+
Cherry-picking can be done as soon as each patch is merged into `main`, or directly before the release.
125149

126-
Cherry-picking can be done as soon as each patch is merged into `main`,
127-
or directly before the release.
150+
The `backport` label automates this: [`backport.yaml`](../.github/workflows/backport.yaml) targets the newest existing `release-X.Y` branch, which during a freeze window is the line being stabilised rather than the last published one.
128151

129152
```mermaid
130153
gitGraph
@@ -178,7 +201,7 @@ gitGraph
178201

179202
The numbered process above is implemented by five workflows. Knowing which job does what makes the failure modes much easier to diagnose.
180203

181-
1. [`cut-prerelease.yaml`](../.github/workflows/cut-prerelease.yaml) — manual dispatch (from `main` or `release-X.Y`): the sole entry point for creating a pre-release tag. Validates the `-alpha`/`-beta`/`-rc` tag, then pushes it (write-once, at the branch tip) as the CI app so `tags.yaml` fires. Stable tags are never created here.
204+
1. [`cut-prerelease.yaml`](../.github/workflows/cut-prerelease.yaml) — manual dispatch (from `main` or `release-X.Y`): the sole entry point for creating a pre-release tag. Validates the `-alpha`/`-beta`/`-rc` tag, then pushes it (write-once, at the branch tip) as the CI app so `tags.yaml` fires. Cutting the first `vX.Y.0-rc.N` also creates `release-X.Y`, freezing the line; afterwards a `vX.Y.*` dispatch from `main` is refused. Stable tags are never created here.
182205
2. [`tags.yaml`](../.github/workflows/tags.yaml) — fires on an rc tag push: runs `prepare-release`, then `generate-changelog`, then `update-website-docs`.
183206
3. [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) — manual dispatch: stages the `release-X.Y.Z` tree (rc digests, tag string rewritten to stable), drafts the stable release, and opens the `release-X.Y.Z` promote PR. No registry mutation — transactional.
184207
4. [`pull-requests-release.yaml`](../.github/workflows/pull-requests-release.yaml) — fires when the `release-X.Y.Z` PR merges; finalizes the release: cuts the write-once stable + Go-module tags, publishes, then retags the rc images to stable by digest (`:latest` gated on newest-stable) and publishes the stable chart.
@@ -236,7 +259,7 @@ Fires on merge of a PR that is merged, carries the `release` label, and is autho
236259

237260
1. **Create the tag at the merge commit** (write-once). The merge commit of `Prepare release vX.Y.Z` did not exist before the PR opened, so there is nothing to move — the tag is created here for the first time. A pre-existing tag at a different commit fails the step loudly rather than being force-moved (see [Tag immutability](#tag-immutability)).
238261
2. **Cut the `api/apps/v1alpha1/vX.Y.Z` Go-module tag** (write-once, stable only) at the same commit, so Go consumers of `api/apps/v1alpha1` get the release. Moved here from `tags.yaml`, whose `prepare-release` body is skipped for a promoted stable (the draft already exists).
239-
3. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing; updated fast-forward-only — a non-fast-forward update warns and is left for a maintainer rather than being force-updated.
262+
3. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Since the rc freeze creates it, this is normally a no-op fast-forward — the merge commit is already the branch tip. Still created if missing; updated fast-forward-only — a non-fast-forward update warns and is left for a maintainer rather than being force-updated.
240263
4. **Publish the draft release.** `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`).
241264
5. **Retag the rc images to stable** by digest (`hack/promote-retag.sh`, no rebuild) and **publish the stable `cozy-installer` chart**. `:latest` (on both the images and the chart) moves only when this release's `make_latest` was `true` — the same decision as step 4, so the release's `latest` and the images' `:latest` never disagree. The chart is packaged with `platformVersion` stamped into its default values so the documented `helm --install --version X.Y.Z` path reports the stable version.
242265

@@ -574,7 +597,7 @@ Sometimes the work that has to land before a release is a 40-commit grab bag (CI
574597

575598
## Cleanup after release
576599

577-
- The `release-X.Y.Z` branch is deleted by GitHub when its PR merges. The `release-X.Y` maintenance branch is created/updated by `pull-requests-release.yaml::Ensure maintenance branch`.
600+
- The `release-X.Y.Z` branch is deleted by GitHub when its PR merges. The `release-X.Y` maintenance branch is created by `cut-prerelease.yaml` at the rc freeze (create-only, never force-moved) and fast-forwarded afterwards by `pull-requests-release.yaml::Ensure maintenance branch`.
578601
- The draft release is published by the same workflow.
579602
- The `update-releasenotes.yaml` workflow syncs `docs/changelogs/vX.Y.Z.md` into the GitHub Release body on the next push to `main`. Edits to a published changelog file land on the release page the next time `main` moves.
580603
- Local cleanup: remove your worktree (`git worktree remove`) and prune merged release branches.

0 commit comments

Comments
 (0)