You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e95a460
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: docs/release.md
+52-29Lines changed: 52 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,18 +29,19 @@ All three are matched by `tags.yaml`'s regex `^v\d+\.\d+\.\d+(-(alpha|beta|rc)\.
29
29
30
30
## Release Candidates
31
31
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.
35
33
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.
40
35
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.
44
45
45
46
## Regular Releases
46
47
@@ -55,52 +56,74 @@ gitGraph
55
56
56
57
A regular release sequence runs as follows:
57
58
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
+
60
74
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:
61
75
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).
62
76
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`.
64
80
65
81
```mermaid
66
82
gitGraph
67
-
commit id: "feature"
68
-
commit id: "feature 2"
69
83
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"
70
87
branch release-1.2.0
71
88
checkout release-1.2.0
72
89
commit id: "Prepare release v1.2.0"
73
-
checkout main
90
+
checkout release-1.2
74
91
merge release-1.2.0 id: "Pull Request"
75
92
```
76
93
77
94
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).
78
95
5. CI workflow triggers on merge (this is where every irreversible side effect happens, all after the PR's e2e passed):
79
96
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.
80
97
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.
82
99
4. Publishes the release page (`draft` → `latest`).
83
100
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.
84
101
6. The maintainer can now announce the release to the community.
Note that `main` never receives the release commit. It forked away at the freeze and carries the next minor's work.
120
+
98
121
## Patch Releases
99
122
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:
101
124
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.
104
127
105
128
106
129
Let's assume that we've released `v1.2.0` and that development is ongoing.
@@ -120,11 +143,11 @@ gitGraph
120
143
```
121
144
122
145
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.
125
149
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.
128
151
129
152
```mermaid
130
153
gitGraph
@@ -178,7 +201,7 @@ gitGraph
178
201
179
202
The numbered process above is implemented by five workflows. Knowing which job does what makes the failure modes much easier to diagnose.
180
203
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.
182
205
2.[`tags.yaml`](../.github/workflows/tags.yaml) — fires on an rc tag push: runs `prepare-release`, then `generate-changelog`, then `update-website-docs`.
183
206
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.
184
207
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
236
259
237
260
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)).
238
261
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.
240
263
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`).
241
264
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.
242
265
@@ -574,7 +597,7 @@ Sometimes the work that has to land before a release is a 40-commit grab bag (CI
574
597
575
598
## Cleanup after release
576
599
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`.
578
601
- The draft release is published by the same workflow.
579
602
- 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.
580
603
- Local cleanup: remove your worktree (`git worktree remove`) and prune merged release branches.
0 commit comments