Release How-to
In this how-to we will explain how can a new release be published step by step. Please refer to the Release Lifecycle document to know more about when to do what type of release.
Setup
Releases are managed using the release-tool project. Each repository can be released independently.
Please install and setup release-tool as described in the repository's README file:
- We typically release using the latest version of the release-tool
which is in
master
branch. - The installation is also very simple, just download the repository and install with pip the requirements in a virtualenv.
- The setup requires creating a github token that has permissions to perform the actions related to the release process.
Preflight checklist: Before creating a release
- Please review the Production Readiness Checklist and ensure everything is ready to create a release.
- Also, review the Release Lifecycle to know when to create what kind of release.
- The release scripts rely on Pull Requests referring to any parent issue with
a line
Parent issue: https://path/to/parent/issue/1
. If you are not sure this has been done for all PRs, use theupdate_parent_issue.py
script to solve it. It will look for closed issues in the meta repository (where usually parent issues land) and add theParent issue: http:/...
line to all linked PRs.
Release procedure overview
Publishing a release is compromised of multiple steps, done for each of the platform repositories:
- Changing the version in the code
The code of the software platform itself usually has some reference to the release. As we are creating a new release, this code needs to be updated.
- Creating a release branch
For example 5.0.x
branch, so that other patch releases fork from there.
This branch needs to be created locally and pushed to the public repository. We
use Release Flow branching methodology.
- Creating a release git tag
Creating the git tag and pushing it to the repository.
Publishing a github release.
Generating the comprehensive release notes.
Each platform repository has now a release, but we want to also generate a comprehensive release notes that merge all the release notes from each platform repository without duplication.
- Removing old and stale release branches. See the Release Lifecycle to know more about release support lifecycle.
Release commands
1. Create the release
You can launch the release of the Sequent platform repositories with the following script, executing steps 1 to 4 detailed previously:
export REPOS=(common-ui admin-console election-portal voting-booth ballot-box deployment-tool tally-methods tally-pipes election-verifier frestq election-orchestra iam misc-tools mixnet documentation ballot-verifier release-tool)
for i in $REPOS
do
./release.py \
--version 7.4.0 \
--change-version \
--base-branch '7.4.x' '7.3.x' \
--push-current-branch \
--create-tag \
--release-title "7.4.0 release" \
--previous-tag-name '7.3.0' \
--generate-release-notes \
--create-release \
--path ../$i
done
Notes:
- We specified multiple branch names with
--base-branch
. This is because in some of the repositories, there might not be any new commits or they might be in the previous7.3.x
branch. The first name of the base-branch will always indicate the final branch to push, and it will use that branch as a base if it does exist. If it's not yet created, the release script will try to use the other given branch names as a base, in order. - We are doing a full release of the full Sequent platform. This requires
having cloned all the related repositories locally in the appropriate path (see
the
../$i
in the script). - It's wise to try first only with one of the repositories to see that
everything goes as expected. You can change the first line to
export REPOS=(common-ui)
for example to give it a try. - Note that the order of the platform repositories listed in the
export REPOS
line is important for automatic unit tests. For example,election-verifier
usestally-pipes
, which in turn depends ontally-methods
. Please do the releasing in order. If you don't, you'll get some github actions failed. If this happens, just rerun the github actions after all the releases have been done and that should fix the problem. - You can add the
--prerelease
to tag a release as a prerelease such as a beta. This command also support more options, use--help
to view them all.
The release.py
script in this configuration will:
- Stash your current changes in the
election-portal
repository - Remove all untracked files and directories (except those ignored by
.gitignore
) - Create a branch from origin/master, commit the changes and force push it to the origin
- Create tag from the just created commit and force push it to the origin
- Create a release from the just created tag
2. Generating the comprehensive release notes
Comprehensive release notes are published in the meta repository. This action can be performed executing the following command:
python comprehensive_release_notes.py 7.3.0 7.4.0 --dry-run
The first release version is the previous release (7.3.0
in the example) and
the second is the new release which we want to create. Remove the --dry-run
to
actually create it. This command also support more options, use --help
to view
them all.
### 3. Removing old and stale release branches
Old releases will go out of support, meaning no new bugfix patch releases are expected to happen. You should go to each of the platform repositories and remove release branches related to them for housekeeping. Right now this is not automated, so you will have to do this manually.
Future
In the future, we should automate the release management command and include them within each different project instead of having a separate repository to handle this.
Some tools we might take a look at to do so:
Also we should automate the releases for the documentation itself, allowing having multiple version of the documentation, to match with the releases.