Skip to content

Commit 19ce2cf

Browse files
NickVolynkinNickVolynkin
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 19ce2cf

1 file changed

Lines changed: 138 additions & 0 deletions

File tree

‎docs/release.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
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 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 the new branch `release-0.42.0`, and opens a PR to `main`.
24+
4. Builds Cozystack release assets 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 are 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. Moves the tag `v0.42.0` to the newly created merge commit by force-pushing a tag to GitHub.
44+
2. Publishes the release page (`draft` → `latest`).
45+
6. The maintainer can now announce the release to the community.
46+
47+
```mermaid
48+
gitGraph
49+
commit id: "feature"
50+
commit id: "feature 2"
51+
commit id: "feature 3"
52+
branch release-0.42.0
53+
checkout release-0.42.0
54+
commit id: "Prepare release v0.42.0"
55+
checkout main
56+
merge release-0.42.0 id: "Release v0.42.0" tag: "v0.42.0"
57+
```
58+
59+
## Patch Releases
60+
61+
Making a patch release has a lot in common with a regular release, with a couple of differences:
62+
63+
* A release branch is used instead of `main`
64+
* Patch commits are cherry-picked to the release branch.
65+
* A pull request is opened against the release branch.
66+
67+
68+
Let's assume that we've released `v0.42.0` and that development is ongoing.
69+
We have introduced a couple of new features and some fixes to features that we have released
70+
in `v0.42.0`.
71+
72+
Once problems were found and fixed, a patch release is due.
73+
74+
```mermaid
75+
gitGraph
76+
commit id: "Release v0.42.0" tag: "v0.42.0"
77+
checkout main
78+
commit id: "feature 4"
79+
commit id: "patch 1"
80+
commit id: "feature 5"
81+
commit id: "patch 2"
82+
```
83+
84+
85+
1. The maintainer creates a release branch, `release-0.42,` and cherry-picks patch commits from `main` to `release-0.42`.
86+
These must be only patches to features that were present in version `v0.42.0`.
87+
88+
Cherry-picking can be done as soon as each patch is merged into `main`,
89+
or directly before the release.
90+
91+
```mermaid
92+
gitGraph
93+
commit id: "Release v0.42.0" tag: "v0.42.0"
94+
branch release-0.42
95+
checkout main
96+
commit id: "feature 4"
97+
commit id: "patch 1"
98+
commit id: "feature 5"
99+
commit id: "patch 2"
100+
checkout release-0.42
101+
cherry-pick id: "patch 1"
102+
cherry-pick id: "patch 2"
103+
```
104+
105+
When all relevant patch commits are cherry-picked, the branch is ready for release.
106+
107+
2. The maintainer tags the `HEAD` commit of branch `release-0.42` as `v0.42.1` and then pushes it to GitHub.
108+
3. CI workflow triggers on tag push:
109+
1. Creates a draft page for release `v0.42.1`, if it wasn't created before.
110+
2. Takes code from tag `v0.42.1`, builds images, and pushes them to ghcr.io.
111+
3. Makes a new commit with updated digests, pushes it to the new branch `release-0.42.1`, and opens a PR to `release-0.42`.
112+
4. Builds Cozystack release assets from this commit, uploads them to the release draft page.
113+
4. Maintainer reviews PR, tests build artifacts, and edits changelogs on the release draft page.
114+
115+
```mermaid
116+
gitGraph
117+
commit id: "Release v0.42.0" tag: "v0.42.0"
118+
branch release-0.42
119+
checkout main
120+
commit id: "feature 4"
121+
commit id: "patch 1"
122+
commit id: "feature 5"
123+
commit id: "patch 2"
124+
checkout release-0.42
125+
cherry-pick id: "patch 1"
126+
cherry-pick id: "patch 2" tag: "v0.42.1"
127+
branch release-0.42.1
128+
commit id: "Prepare release v0.42.1"
129+
checkout release-0.42
130+
merge release-0.42.1 id: "Pull request"
131+
```
132+
133+
Finally, when release is confirmed, the release sequence goes on.
134+
135+
5. Maintainer merges the PR. GitHub removes the merged branch `release-0.42.1`.
136+
6. The CI workflow moves the tag `v0.42.1` to the newly created merge commit by force-pushing a tag to GitHub.
137+
7. CI workflow publishes the release page (`draft` → `latest`).
138+
8. The maintainer can now announce the release to the community.

0 commit comments

Comments
 (0)