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 5885f6a
Browse filesBrowse the repository at this point in the historyBrowse files
docs(release): reconcile the stable-tag flow to promotion-only
Address review feedback from coderabbitai on docs/release.md: the Regular and
Patch sections still told maintainers to push vX.Y.Z to start the build, while
the rest of the doc said the stable tag is created write-once at the merge
commit and stable comes only from rc promotion (with a 'can also push directly'
escape hatch). Rewrite both sections to the single promotion model — push an rc,
promote it via promote-rc.yaml, merge the promote PR, finalize creates the
write-once tag — drop the direct-push escape hatch, and add promote-rc.yaml to
the workflow list.
Assisted-By: Claude <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Signed-off-by: Myasnikov Daniil <[email protected]>
Copy file name to clipboardExpand all lines: docs/release.md
+30-36Lines changed: 30 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,51 +44,49 @@ This begins the regular release process, creates a dedicated `release-X.Y` branc
44
44
45
45
## Regular Releases
46
46
47
-
When making a regular release, we tag the latest RC or a subsequent minimal-change commit as `vX.Y.0`.
48
-
In this explanation, we'll use version `v1.2.0` as an example:
47
+
A regular release `vX.Y.0` is **promoted from a release-candidate that already passed e2e** — never tagged by hand and never rebuilt. The bytes shipped as `vX.Y.0` are the exact `vX.Y.0-rc.N` images, retagged by digest. We'll use `v1.2.0` as an example.
49
48
50
49
```mermaid
51
50
gitGraph
52
51
commit id: "feature"
53
52
commit id: "feature 2"
54
-
commit id: "feature 3" tag: "v1.2.0"
53
+
commit id: "feature 3" tag: "v1.2.0-rc.1"
55
54
```
56
55
57
-
A regular release sequence starts in the following way:
56
+
A regular release sequence runs as follows:
58
57
59
-
1.Maintainer tags a commit in`main` with `v1.2.0`and pushes it to GitHub.
60
-
2.CI workflow triggers on tag push:
61
-
1. Creates a draft page for release `v1.2.0`, if it wasn't created before.
62
-
2. Takes code from tag `v1.2.0`, builds images, and pushes them to ghcr.io.
63
-
3. Makes a new commit `Prepare release v1.2.0`with updated digests, pushes it to the new branch `release-1.2.0`, and opens a PR to `main`.
64
-
4. Builds Cozystack release assets from the new commit `Prepare release v1.2.0` and uploads them to the release draft page.
65
-
3. Maintainer reviews PR, tests build artifacts, and edits changelogs on the release draft page.
58
+
1.Tag the last good commit on`main`as a release candidate (`v1.2.0-rc.N`) and push it with `git push origin HEAD:refs/tags/v1.2.0-rc.N`. CI 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.
60
+
3. Once an rc is green, run the [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) workflow (manual dispatch) with that rc tag. It:
61
+
1. Retags the rc's images by digest to `v1.2.0`and `:latest` — no rebuild.
62
+
2. Pushes the `release-1.2.0`branch: the rc's digest-vendored tree with the rc version substring rewritten to `1.2.0`.
63
+
3. Drafts the `v1.2.0`release and uploads the (restamped) assets.
64
+
4. Opens the `chore(release): promote v1.2.0-rc.N -> v1.2.0` PR into `main`.
66
65
67
66
```mermaid
68
67
gitGraph
69
68
commit id: "feature"
70
69
commit id: "feature 2"
71
-
commit id: "feature 3" tag: "v1.2.0"
70
+
commit id: "feature 3" tag: "v1.2.0-rc.1"
72
71
branch release-1.2.0
73
72
checkout release-1.2.0
74
73
commit id: "Prepare release v1.2.0"
75
74
checkout main
76
75
merge release-1.2.0 id: "Pull Request"
77
76
```
78
77
79
-
When testing and editing are completed, the sequence goes on.
80
-
81
-
4. Maintainer merges the PR. GitHub removes the merged branch `release-1.2.0`.
78
+
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`.
82
79
5. CI workflow triggers on merge:
83
80
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.
84
-
2. Publishes the release page (`draft` → `latest`).
81
+
2. Ensures the `release-1.2` maintenance branch exists at the tag commit.
82
+
3. Publishes the release page (`draft` → `latest`).
85
83
6. The maintainer can now announce the release to the community.
86
84
87
85
```mermaid
88
86
gitGraph
89
87
commit id: "feature"
90
88
commit id: "feature 2"
91
-
commit id: "feature 3"
89
+
commit id: "feature 3" tag: "v1.2.0-rc.1"
92
90
branch release-1.2.0
93
91
checkout release-1.2.0
94
92
commit id: "Prepare release v1.2.0"
@@ -100,9 +98,8 @@ gitGraph
100
98
101
99
Making a patch release has a lot in common with a regular release, with a couple of differences:
102
100
103
-
* A release branch is used instead of `main`
104
-
* Patch commits are cherry-picked to the release branch.
105
-
* A pull request is opened against the release branch.
101
+
* The rc and its promotion happen on the `release-X.Y` maintenance branch instead of `main`.
102
+
* Patch commits are cherry-picked to that branch before the rc is tagged.
106
103
107
104
108
105
Let's assume that we've released `v1.2.0` and that development is ongoing.
@@ -144,14 +141,10 @@ gitGraph
144
141
145
142
When all relevant patch commits are cherry-picked, the branch is ready for release.
146
143
147
-
2. The maintainer tags the `HEAD` commit of branch `release-1.2` as `v1.2.1` and then pushes it to GitHub.
148
-
3. CI workflow triggers on tag push:
149
-
1. Creates a draft page for release `v1.2.1`, if it wasn't created before.
150
-
2. Takes code from tag `v1.2.1`, builds images, and pushes them to ghcr.io.
151
-
3. Makes a new commit `Prepare release v1.2.1` with updated digests, pushes it to the new branch `release-1.2.1`, and opens a PR to `release-1.2`.
152
-
4. Builds Cozystack release assets from the new commit `Prepare release v1.2.1` and uploads them to the release draft page.
153
-
4. Maintainer reviews PR, tests build artifacts, and edits changelogs on the release draft page.
154
-
144
+
2. The maintainer tags the `HEAD` commit of branch `release-1.2` as a release candidate (`v1.2.1-rc.N`) and pushes it. CI builds the rc images, drafts the rc release, and pushes the `release-1.2.1-rc.N` staging branch.
145
+
3. Validate the rc.
146
+
4. Once the rc is green, run [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) (manual dispatch) with that rc tag. It retags the rc images by digest to `v1.2.1`, pushes the `release-1.2.1` branch, drafts the `v1.2.1` release with the restamped assets, and opens the promote PR into `release-1.2`.
147
+
155
148
```mermaid
156
149
gitGraph
157
150
commit id: "Release v1.2.0" tag: "v1.2.0"
@@ -163,7 +156,7 @@ gitGraph
163
156
commit id: "patch 2"
164
157
checkout release-1.2
165
158
cherry-pick id: "patch 1"
166
-
cherry-pick id: "patch 2" tag: "v1.2.1"
159
+
cherry-pick id: "patch 2" tag: "v1.2.1-rc.1"
167
160
branch release-1.2.1
168
161
commit id: "Prepare release v1.2.1"
169
162
checkout release-1.2
@@ -172,23 +165,24 @@ gitGraph
172
165
173
166
Finally, when release is confirmed, the release sequence goes on.
174
167
175
-
5. Maintainer merges the PR. GitHub removes the merged branch `release-1.2.1`.
168
+
5. Maintainer reviews and merges the PR — **do not squash-merge**. GitHub removes the merged branch `release-1.2.1`.
176
169
6. CI workflow triggers on merge:
177
170
1. Creates the tag `v1.2.1` at the newly created merge commit — write-once. The tag is published here for the first time, never moved.
178
171
2. Publishes the release page (`draft` → `latest`).
179
172
7. The maintainer can now announce the release to the community.
180
173
181
174
## What CI does on a tag push
182
175
183
-
The numbered process above is implemented by three workflows. Knowing which job does what makes the failure modes much easier to diagnose.
176
+
The numbered process above is implemented by four workflows. Knowing which job does what makes the failure modes much easier to diagnose.
184
177
185
-
1.[`tags.yaml`](../.github/workflows/tags.yaml) — runs `prepare-release`, then `generate-changelog`, then `update-website-docs`.
186
-
2.[`pull-requests-release.yaml`](../.github/workflows/pull-requests-release.yaml) — fires later when the `release-X.Y.Z` PR merges; finalizes the release.
187
-
3.[`update-releasenotes.yaml`](../.github/workflows/update-releasenotes.yaml) — fires on every push to `main`; syncs `docs/changelogs/v*.md` content into the corresponding GitHub Release body.
178
+
1.[`tags.yaml`](../.github/workflows/tags.yaml) — fires on an rc tag push: runs `prepare-release`, then `generate-changelog`, then `update-website-docs`.
179
+
2.[`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) — manual dispatch: retags a green rc to stable by digest and opens the `release-X.Y.Z` promote PR.
180
+
3.[`pull-requests-release.yaml`](../.github/workflows/pull-requests-release.yaml) — fires later when the `release-X.Y.Z` PR merges; finalizes the release (creates the write-once stable tag, publishes).
181
+
4.[`update-releasenotes.yaml`](../.github/workflows/update-releasenotes.yaml) — fires on every push to `main`; syncs `docs/changelogs/v*.md` content into the corresponding GitHub Release body.
188
182
189
183
### Phase 1 — `prepare-release` (hard gate)
190
184
191
-
Builds images, commits digest pins, creates the draft release, creates the `release-X.Y.Z`branch, opens the `chore(release): cut vX.Y.Z` PR.
185
+
On an rc tag push: builds images, commits digest pins, creates the draft release, and pushes the `release-X.Y.Z-rc.N` staging branch. (The stable promote PR is opened later by `promote-rc.yaml`, not here. When the stable tag itself is pushed by finalize, a draft already exists, so this job is a no-op — see [Phase 5](#phase-5--pull-requests-releaseyaml-finalize).)
192
186
193
187
The commit (`Prepare release vX.Y.Z`, authored by `cozystack-ci[bot]`) is **digest pins and image tags only**:
194
188
@@ -250,7 +244,7 @@ A stable `vX.Y.Z` is created only by **promoting an existing release-candidate**
250
244
251
245
-[`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) is triggered manually once an rc has gone green. It retags the rc's already-built, e2e-passed image digests to the stable tag **by digest** (no rebuild — see [`hack/promote-retag.sh`](../hack/promote-retag.sh)), rewrites the rc version substring in the vendored `values.yaml` tags, and opens the `release-X.Y.Z` staging PR. Merging that PR creates the write-once stable tag at the merge commit (Phase 5) and publishes the release. Because the copy source is the immutable rc digest, the stable image is bit-for-bit the rc image that passed e2e.
252
246
253
-
So a commit on a supported `release-X.Y` line ships when a maintainer promotes the next rc for that line — not automatically within 24h. A maintainer can also cut any branch directly by pushing a `vX.Y.Z` tag; [`tags.yaml`](../.github/workflows/tags.yaml) fires on any `v*.*.*` tag push.
247
+
So a commit on a supported `release-X.Y` line ships when a maintainer promotes the next rc for that line — not automatically within 24h. Pushing a stable `vX.Y.Z` tag by hand is **not** a supported path: the finalize step creates that tag write-once at the promote PR's merge commit (Phase 5) and refuses to move a pre-existing one, so a hand-pushed stable tag only collides with the promotion flow. Release candidates (`vX.Y.Z-rc.N`) are still pushed by hand — [`tags.yaml`](../.github/workflows/tags.yaml) fires on the rc tag push and builds it.
0 commit comments