Skip to content

Commit 25a2f0c

Browse files
committed
[docs] Describe the Cozystack release workflow
Resolves #127 Co-authored-by: Andrei Kvapil <[email protected]> Signed-off-by: Nick Volynkin <[email protected]>
1 parent 86210c1 commit 25a2f0c

1 file changed

Lines changed: 140 additions & 0 deletions

File tree

‎docs/release.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Release Workflow
2+
3+
This section explains how Cozystack builds and releases are made.
4+
5+
## Regular Releases
6+
7+
When making regular releases, we just take a commit in `main` and decide to make it a release `x.y.0`.
8+
In this explanation we'll use version `v0.42.0` as an example:
9+
10+
```mermaid
11+
gitGraph
12+
commit id: "feature"
13+
commit id: "feature 2"
14+
commit id: "feature 3" tag: "v0.42.0"
15+
```
16+
17+
A regular release sequence starts in the following way:
18+
19+
1. Maintainer tags a commit in `main` with `v0.42.0` and pushes it to GitHub.
20+
2. CI workflow triggers on tag push:
21+
1. Creates a draft page for release `v0.42.0`, if it wasn't created before.
22+
2. Takes code from tag `v0.42.0`, builds images, and pushes them to ghcr.io.
23+
3. Makes a new commit with updated digests, pushes it to new branch `release-0.42.0`, and opens a PR to `main`.
24+
4. Builds Cozystack distributives (except images) from this commit, uploads them to the release draft page.
25+
3. Maintainer reviews PR, tests build artifacts, and edits changelogs on the release draft page.
26+
27+
```mermaid
28+
gitGraph
29+
commit id: "feature"
30+
commit id: "feature 2"
31+
commit id: "feature 3" tag: "v0.42.0"
32+
branch release-0.42.0
33+
checkout release-0.42.0
34+
commit id: "Prepare release v0.42.0"
35+
checkout main
36+
merge release-0.42.0 id: "Pull Request"
37+
```
38+
39+
When testing and editing is completed, the sequence goes on.
40+
41+
4. Maintainer merges the PR. GitHub removes the merged branch `release-0.42.0`.
42+
5. CI workflow triggers on merge:
43+
1. Publishes the release page (`draft` → `latest`).
44+
2. Moves the tag `v0.42.0` to the newly created merge commit by force-pushing a tag to GitHub.
45+
6. Another CI workflow triggers on the new tag push, checks that release is already published, and stops.
46+
7. Maintainer can now announce release to community.
47+
48+
```mermaid
49+
gitGraph
50+
commit id: "feature"
51+
commit id: "feature 2"
52+
commit id: "feature 3"
53+
branch release-0.42.0
54+
checkout release-0.42.0
55+
commit id: "Prepare release v0.42.0"
56+
checkout main
57+
merge release-0.42.0 id: "Release v0.42.0" tag: "v0.42.0"
58+
```
59+
60+
## Patch Releases
61+
62+
Making a patch release has a lot in common with regular release, with a couple of differences:
63+
64+
* A release branch is used instead of `main`
65+
* Patch commits are cherry-picked to the release branch.
66+
* A pull request is opened against the release branch.
67+
68+
69+
Let's assume that we've released `v0.42.0` and development goes on.
70+
We have introduced a couple of new features and some fixes to features which we have released
71+
in `v0.42.0`.
72+
73+
Once problems were found and fixed, a patch release is due.
74+
75+
```mermaid
76+
gitGraph
77+
commit id: "Release v0.42.0" tag: "v0.42.0"
78+
checkout main
79+
commit id: "feature 4"
80+
commit id: "patch 1"
81+
commit id: "feature 5"
82+
commit id: "patch 2"
83+
```
84+
85+
86+
1. Maintainer makes a release branch `release-0.42` and cherry-picks patch commits from `main` to `release-0.42`.
87+
These must be only patches to features that were present in version `v0.42.0`.
88+
89+
Cherry-picking can be done as soon as each patch is merged in `main`,
90+
or directly before the release.
91+
92+
```mermaid
93+
gitGraph
94+
commit id: "Release v0.42.0" tag: "v0.42.0"
95+
branch release-0.42
96+
checkout main
97+
commit id: "feature 4"
98+
commit id: "patch 1"
99+
commit id: "feature 5"
100+
commit id: "patch 2"
101+
checkout release-0.42
102+
cherry-pick id: "patch 1"
103+
cherry-pick id: "patch 2"
104+
```
105+
106+
When all relevant patch commits are cherry-picked, the branch is ready for releasing.
107+
108+
2. Maintainer tags the `HEAD` commit of branch `release-0.42` as `v0.42.1`, then pushes it to GitHub.
109+
3. CI workflow triggers on tag push:
110+
1. Creates a draft page for release `v0.42.1`, if it wasn't created before.
111+
2. Takes code from tag `v0.42.1`, builds images, and pushes them to ghcr.io.
112+
3. Makes a new commit with updated digests, pushes it to new branch `release-0.42.1`, and opens a PR to `release-0.42`.
113+
4. Builds Cozystack distributives (except images) from this commit, uploads them to the release draft page.
114+
4. Maintainer reviews PR, tests build artifacts, and edits changelogs on the release draft page.
115+
116+
```mermaid
117+
gitGraph
118+
commit id: "Release v0.42.0" tag: "v0.42.0"
119+
branch release-0.42
120+
checkout main
121+
commit id: "feature 4"
122+
commit id: "patch 1"
123+
commit id: "feature 5"
124+
commit id: "patch 2"
125+
checkout release-0.42
126+
cherry-pick id: "patch 1"
127+
cherry-pick id: "patch 2" tag: "v0.42.1"
128+
branch release-0.42.1
129+
commit id: "Prepare release v0.42.1"
130+
checkout release-0.42
131+
merge release-0.42.1 id: "Pull request"
132+
```
133+
134+
Finally, when release is confirmed, the release sequence goes on.
135+
136+
5. Maintainer merges the PR. GitHub removes the merged branch `release-0.42.1`.
137+
6. CI workflow publishes the release page (`draft` → `latest`).
138+
7. CI workflows moves the tag `v0.42.1` to the newly created merge commit. Moving is done by force-pushing to GitHub.
139+
- Another CI workflow triggers on the new tag push, checks that release is not in draft and stops.
140+
8. Maintainer can now announce release to community.

0 commit comments

Comments
 (0)