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
Copy file name to clipboardExpand all lines: docs/source/procedures/creating-releases.rst
+80-20Lines changed: 80 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,49 +2,109 @@ The Augur Release Process
2
2
=========================
3
3
4
4
The first step to releasing any changes is to have changes in the first place.
5
-
Augur's `CONTRIBUTING.md <https://github.com/chaoss/augur/blob/main/CONTRIBUTING.md>`__ file contains all the information that is needed to get started with topics like reporting issues, contributing code, and understanding the code review process.
contains all the information that is needed to get started with topics like
7
+
reporting issues, contributing code, and understanding the code review process.
6
8
7
9
This document outlines how these changes end up in an Augur release after they are merged into the `main` branch.
8
10
11
+
Release Workflow
12
+
----------------
9
13
10
-
11
-
Release workflow:
12
-
Starting after version 0.89.3, Augur follows a workflow similar to those you may already be familiar with (such as github flow and git flow). The Augur workflow has two long-lived branches, `main` and `release` and is designed such that changes only flow in one direction - from main into release.
14
+
Starting after version **0.89.3**, Augur follows a workflow similar to those you may already
15
+
be familiar with (such as GitHub Flow and Git Flow). The Augur workflow has two long-lived branches,
16
+
`main` and `release`, and is designed such that changes only flow in one direction — from `main` into `release`.
13
17
14
18
Branches
19
+
--------
20
+
21
+
**main**
15
22
16
-
`main`
17
-
The `main` branch is the primary development branch that is the target for all new pull requests. At any given point in time, this branch represents the best approximation of what the next upcoming release will look like. Since this is the active development branch, changes happen more frequently and this branch should be considered to be less stable than the `release` branch due to the possibility of breaking changes being made (and potentially reverted) between releases. It is not recommended for production deployment and is primarily intended for use by Augur contributors running their own copies against test data for development purposes.
23
+
The `main` branch is the primary development branch that is the target for all new pull requests.
24
+
At any given point in time, this branch represents the best approximation of what the next upcoming
25
+
release will look like. Since this is the active development branch, changes happen more frequently
26
+
and this branch should be considered to be less stable than the `release` branch due to the possibility
27
+
of breaking changes being made (and potentially reverted) between releases. It is not recommended for
28
+
production deployment and is primarily intended for use by Augur contributors running their own copies
29
+
against test data for development purposes.
18
30
19
-
`release`
20
-
The `release` branch is where all augur versions (after 0.89.3) are tagged. Each commit on this branch represents either a hotfix to the prior release or a new major or minor version.
31
+
**release**
21
32
22
-
Currently, Augur only officially supports the last-released version represented by the latest **release** tag. In most cases, the latest commit on the `release` branch is made immediately prior to a release, but always rely on the latest tagged release, not the release branch in production.
33
+
The `release` branch is where all Augur versions (after 0.89.3) are tagged. Each commit on this branch
34
+
represents either a hotfix to the prior release or a new major or minor version.
35
+
36
+
Currently, Augur only officially supports the last-released version represented by the latest **release** tag.
37
+
In most cases, the latest commit on the `release` branch is made immediately prior to a release, but always rely
38
+
on the latest tagged release, not the `release` branch in production.
23
39
24
40
.. note::
25
41
26
-
If future needs require supporting multiple Augur versions concurrently, individual numbered release branches may be made from this central `release`` branch to allow any hotfixes to be applied to each supported version independently of the others.
- Any scripts or documentation pages referencing specific versions
34
67
35
-
Once all release preparation has been completed, a new Pull Request can be created to merge the main branch into the `release 'branch. This creates a final review opportunity and allows for another run of (potentially more stringent) CI jobs compared to those run on `main`, catching issues that may have come up throughout the various merges or in the process of preparing for release.
68
+
This manual process increased the chance of version mismatches between code, Docker images, and releases.
36
69
37
-
After this PR is merged, a tag is created that points to the commit on the `release` branch, effectively labeling it so that it can be returned to later if needed. This labeling process can also be the basis for additional CI jobs that build and upload the released code to distribution platforms such as Docker Hub or the GitHub Container Registry
70
+
Now, this has been **fully centralized**:
71
+
72
+
- The version number is declared once in ``metadata.py`` as ``__version__``.
73
+
- A helper script ``get_version.py`` reads this value and dynamically injects it into Docker builds via a build argument.
74
+
- The CI/CD pipeline (GitHub Actions) also reads the same version from ``metadata.py`` when tagging builds and Docker images.
75
+
76
+
This ensures that all parts of Augur — including Python packaging, Docker images, and release artifacts —
77
+
use the **exact same version**, automatically.
78
+
79
+
Therefore, before tagging a new release, only the version in ``metadata.py`` needs to be updated.
80
+
All other build and deployment steps automatically consume this version during the release process.
81
+
82
+
Once all release preparation has been completed, a new Pull Request can be created to merge the `main`
83
+
branch into the `release` branch. This creates a final review opportunity and allows for another run of
84
+
(potentially more stringent) CI jobs compared to those run on `main`, catching issues that may have come up
85
+
throughout the various merges or during the process of preparing for release.
86
+
87
+
After this PR is merged, a tag is created that points to the commit on the `release` branch,
88
+
effectively labeling it so that it can be returned to later if needed. This labeling process can
89
+
also be the basis for additional CI jobs that build and upload the released code to distribution
90
+
platforms such as Docker Hub or the GitHub Container Registry.
38
91
39
92
40
93
Why?
94
+
----
41
95
42
96
This is done to solve a number of problems:
43
-
- having changes moving in two directions at once (i.e. features coming from main, and hotfixes coming from release) was often confusing and increased the odds that a change would be missed, such as being shipped as a hotfix but not merged into the main codebase - leading to a regression in the next release.
44
97
98
+
- Having changes moving in two directions at once (i.e. features coming from `main`, and hotfixes coming from `release`)
99
+
was often confusing and increased the odds that a change would be missed, such as being shipped as a hotfix
100
+
but not merged into the main codebase — leading to a regression in the next release.
101
+
102
+
103
+
Special Case: Hotfixes
104
+
----------------------
45
105
106
+
If the fix is a hotfix:
46
107
47
-
Special case: Hotfixes
48
-
if the fix was a hotfix:
49
-
- changelog updates and other metadata changes should be included as part of the PR
50
-
- this is where mergeify or something helps re-create the PR targeting the release branch directly. at which point the release process is followed
108
+
- Changelog updates and other metadata changes should be included as part of the PR.
109
+
- This is where tools like **Mergeify** can help re-create the PR targeting the `release` branch directly,
110
+
at which point the regular release process is followed.
0 commit comments