Skip to content

Commit bd7a92e

Browse files
vsbogdvsbogd
authored
Merge pull request #356 from janaina-senna/jn/docs/release-process
docs: add release process to the documentation
2 parents 78c6691 + 4444467 commit bd7a92e

1 file changed

Lines changed: 202 additions & 0 deletions

File tree

‎docs/development/release-process.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Omega - Release Process
2+
3+
This document describes the current process for releasing a new version of Omega, using the `v0.2.0` release as an example.
4+
5+
## Process Overview
6+
7+
The Omega release process has two main phases:
8+
9+
* **Phase 1: Version Preparation and Validation**
10+
* **Phase 2: Release Publication and Promotion**
11+
12+
| **Phase** | **Stage** | **What happens** |
13+
| --------- | --------------------------- | --------------------------------------------------------------- |
14+
| **1** | **PR development** | Code is developed and tested before merging to `main` |
15+
| | **QA validation** | QA builds and tests the PR code locally. When needed, a <br>Docker image can also be built and published manually |
16+
| | **Merge to `main`** | The approved PR is merged into `main` |
17+
| **2** | **GitHub Release** | A version such as `v0.2.0` is created and published |
18+
| | **Release build** | The release workflow builds the formal release Docker image |
19+
| | **QA approval** | QA approves the release image |
20+
| | **Administrative approval** | Final administrative approval is granted |
21+
| | **Promotion** | The release image receives the final tags `v0.2.0` and `latest` |
22+
23+
### Important Distinction
24+
25+
There are two different types of builds in the current process:
26+
27+
* The **PR build**, which QA typically performs locally while the code is still under development. This build does not normally result in a Docker image being published to Docker Hub.
28+
29+
* The **release build**, which is performed after the PR is merged and the GitHub Release is published. This build produces the formal release Docker image that is ultimately promoted to the final Docker tags.
30+
31+
For PR testing, the `manual.yml` workflow can be triggered to build and publish a Docker image to Docker Hub. This is a manual process and is not required for every PR.
32+
33+
---
34+
35+
# Phase 1: Version Preparation and Validation
36+
37+
## 1. PR Development and Testing
38+
39+
During development, the code remains in a Pull Request (PR).
40+
41+
QA manually tests the PR by building the code locally on their machine using the current PR commit.
42+
43+
As an alternative, when a Docker image is needed for testing or other purposes, the image can be built and published manually through the manual.yml workflow.
44+
45+
The workflow is manually triggered with:
46+
47+
```yaml
48+
publish_docker: true
49+
```
50+
51+
When this option is enabled, the workflow builds the Docker image from the selected commit and publishes it to Docker Hub. The image is tagged with the corresponding Git commit SHA.
52+
53+
The workflow then calls the reusable `common.yml` workflow.
54+
55+
Example images:
56+
57+
```text
58+
singularitynet/omega:764ec8251cc09632d2d92566a3e5d7817eb948e6
59+
singularitynet/omega:6e9f0fbb944b64d15a4ee5b668be874619d9378a
60+
```
61+
62+
The manual Docker image publication is optional and does not represent a mandatory step in the PR validation process.
63+
64+
---
65+
66+
## 2. Merge the PR into `main`
67+
68+
Once QA has completed testing and any required fixes have been made, the PR is merged into `main`.
69+
70+
The merge automatically triggers `build.yml`.
71+
72+
`build.yml`:
73+
74+
* Runs the test suite.
75+
* Builds the application.
76+
* Performs the normal CI checks.
77+
* Does **not** publish the formal release Docker image.
78+
79+
At this point, the code is in `main`, but the formal release process has not started yet.
80+
81+
---
82+
83+
# Phase 2: Release Publication and Promotion
84+
85+
## 3. Create and Publish the GitHub Release
86+
87+
Once the code intended for release is in `main`, a GitHub Release is created through the GitHub UI, for example, `v0.2.0`.
88+
89+
Publishing the GitHub Release generates the `release.published` event. This event triggers:
90+
91+
```text
92+
.github/workflows/release.yml
93+
```
94+
95+
This is the point at which the formal release process begins.
96+
97+
---
98+
99+
## 4. Build the Release Image
100+
101+
`release.yml` calls the reusable `common.yml` workflow with the following parameters:
102+
103+
```yaml
104+
publish_docker: true
105+
tag_name: ${{ github.sha }}
106+
move_latest: false
107+
```
108+
109+
The workflow then:
110+
111+
1. Builds the application.
112+
2. Builds the Docker image.
113+
3. Runs the required tests.
114+
4. Publishes the image to Docker Hub using the release commit SHA.
115+
116+
The resulting image has a tag similar to:
117+
118+
```text
119+
singularitynet/omega:<release-sha>
120+
```
121+
122+
---
123+
124+
## 5. QA Approval
125+
126+
After the release image has been built and published, the workflow reaches the `qa-approval` job.
127+
128+
This job uses the GitHub Environment:
129+
130+
```text
131+
dockerhub-production
132+
```
133+
134+
The environment is configured to require approval.
135+
136+
The workflow waits until the required QA approval is granted.
137+
138+
No new Docker image is built during this step.
139+
140+
---
141+
142+
## 6. Administrative Approval
143+
144+
After QA approval, the workflow reaches the `admin-approval` job.
145+
146+
This job uses the GitHub Environment:
147+
148+
```text
149+
dockerhub-admin-approval
150+
```
151+
152+
A second approval is required before the image can be promoted to the final tags.
153+
154+
Again, no new Docker image is built during this step.
155+
156+
---
157+
158+
## 7. Promote the Image to the Final Tags
159+
160+
Once both approvals have been granted, the `update-tags` job promotes the SHA-tagged release image.
161+
162+
For the `v0.2.0` release, the final tags are:
163+
164+
```text
165+
singularitynet/omega:v0.2.0
166+
singularitynet/omega:latest
167+
```
168+
169+
No new Docker image is built at this stage.
170+
171+
Instead, `docker buildx imagetools create` is used to create new references to the already-published release image.
172+
173+
Conceptually:
174+
175+
```text
176+
singularitynet/omega:<release-sha>
177+
│
178+
├──► singularitynet/omega:v0.2.0
179+
│
180+
└──► singularitynet/omega:latest
181+
```
182+
183+
This means that the final tags point to the same image that was built and approved during the release process.
184+
185+
---
186+
187+
# Key Points
188+
189+
* QA builds and tests the PR code locally before it is merged into `main`.
190+
* The Git commit SHA identifies the specific PR commit being tested.
191+
* A Docker image can optionally be built and published to Docker Hub through the manually triggered `manual.yml` workflow.
192+
* When `manual.yml` is used to publish an image, the image is tagged with the corresponding Git commit SHA.
193+
* Merging into `main` triggers the normal CI workflow through `build.yml`.
194+
* `build.yml` does **not** publish the formal release image.
195+
* The formal release starts when a GitHub Release is published.
196+
* `release.yml` builds and publishes a new release image.
197+
* The release image is identified by the release commit SHA.
198+
* QA approval happens after the release image has been built.
199+
* Administrative approval happens after QA approval.
200+
* The final `v0.2.0` and `latest` tags are created by referencing the already-built release image.
201+
* No new image is built during the final tag promotion.
202+

0 commit comments

Comments
 (0)