Release process - msupply-foundation/open-msupply GitHub Wiki
One Open mSupply team will be responsible for releasing. This will be rotated every two release cycles.
On top of managing the milestone and creating the release, the release team will:
- Triage incoming bugs
- Liaise with QA
- Update docs before the release
Bugs are created with the needs daily triage
and needs triage
labels. Each day, someone from the release team should review all bugs with the needs daily triage
label assigned.
If the bug is critical and requires a hot fix:
- The
Severity: Hotfix
label should be assigned - Milestone should be assigned (either patch or current RC)
- A team should be assigned to implement the fix immediately
- Both the
needs daily triage
andneeds triage
labels should be removed
For non-critical bugs:
- Assign a preliminary severity label to help the triage team
- Remove the
needs daily triage
label, keepneeds triage
- The bug will be properly triaged by the triage team at the next weekly meeting
This is the process followed when creating a release. It's written out here as a knowledge sharing process really, those of you who do the releases will know most of this, though perhaps a checklist or reference is helpful.
Here's an outline of the steps to take when making a release. Think of this as your cheatsheet - for more information see the sections below
- Check that weblate has pushed all changes to the repo before making the release branch!
- Git fetch
- Pull release branch & main
- (maybe) Bump the version in the root
package.json
- Push the changes
- Add tag
git tag vX.Y.Z
- Push tag
git push origin vX.Y.Z
- Create android build
- Draft a new pre-release on GitHub
- Edit details
- Upload assets
- Merge feature branch to main
- Merge main to develop
- Delete the release branch
- Post in
omSupply Releases
in Telegram to announce the new release
This is the branching strategy that we're using (ref)
Branch | Protected? | Base Branch | Description |
---|---|---|---|
main |
YES | N/A | What is live in production (stable). A pull request is required to merge code into main . |
develop |
YES | main |
The latest state of development (unstable). |
feature | NO | develop |
Cutting-edge features (unstable). These branches are used for any maintenance features / active development. |
release-vX.Y.Z |
NO | develop |
A temporary release branch that follows the semver versioning. This is what is sent to UAT. A pull request is required to merge code into any release-vX.Y.Z branch. |
hotfix-* |
NO | main |
These are bug fixes against production. This is used because develop might have moved on from the last published state. Remember to merge this back into develop and any release branches. |
When it comes to release time, the process is as follows:
We create the release candidate branch after PR merge deadline.
-
Merge
main
intodevelop
to ensure the new release will contain the latest production code. This reduces the chance of a merge conflict during the release.$ git checkout develop $ git merge main
-
Create a new
release-vX.Y.Z
release branch off ofdevelop
.$ git checkout -b release-vX.Y.Z $ git push --set-upstream release-vX.Y.Z
-
Create a new milestone
vX.Y.Z-RCx
(Replace with next RC version for history) and move all the uncompleted issues for version into this milestone so testers know which bugs have been fixed with what version in their tester board. From here, any bug fixes as a result of QA will go into the release branch -
When the code is ready to release, navigate to the project on Github and open a pull request with the following branch settings:
- Base:
main
- Compare:
release-vX.Y.Z
Update with details of the release
- Base:
-
If the version hasn't been bumped in the root
package.json
then do this now -
At some point in the checklist you will merge the release branch into
main
. You can do this by using the "Merge pull request" button on the release PR. -
Add a tag, this will start a build process on Jenkins
git tag vX.Y.Z git push origin tag vX.Y.Z
note that for the Jenkins build, the tag must start with
v
-
Create the android build
cd ./client yarn android:build:release
-
Now you are ready to create the actual release. Navigate to the project page on Github and draft a new release (or pre-release for RC versions)
-
Click on the Draft a new release button:
-
Click on Choose a tag
-
Select vX.Y.Z from the list
-
This should set the 'previous tag' to 'auto'. Enter the tag as the heading of the release:
-
Edit the description. This is the format used:
### What's in this release [a brief description of the highlights] #### Features - [bullet point for each feature, with a one-liner about them] #### Bugs fixed - #[issue number] [hand crafted description] **Full Changelog**: https://github.com/openmsupply/open-msupply/compare/v1.1.14...v1.1.15
You will find it helpful to click the Generate release notes button. This will give you a list of all PRs merged in this release. From there you can rewrite descriptions and gather up a list of changes.
- Upload the assets
- Android apk which you've just built
- All the assets from the jenkins build. Note that dropbox is much faster to download from!
- Set as latest release
- Click
Publish release
- Post in
omSupply Releases
in Telegram to announce the new release
-
-
Move all completed issues that are in milestone
vX.Y.Z-RCx
into the version milestone. -
Update docs for current version (see below)
-
Do daily triage for critical bugs that may stop the user from using some functionality and add them to the RCx milestone.
-
Evenly assign bug issues to each team.
Public documentation for new features should be written by the team that built the feature. However, PRs for bug fixes/small enhancements throughout the cycle which have UI changes will be assigned a docs: external
label.
Once in the testing sprint, filter Done
PRs by docs: external
, and update any relevant screenshots/descriptions. The docs: external
label can then be replaced with docs: done
.
Note: QA should always be using the latest RC build for their tests. This means that they should swap to the new RC version if it is available for the rest of their testing.
- Write up/update test suites as required
- Create an epic issue that links to every test suite issue.
- Test new features first
- Go through the rest of the other test suites
- Once the test suites have been completed, individual bug issues can be tested. QA team gets this from their tester board, so please correctly label every issue with the correct milestone.
-
Merge the
release-vX.Y.Z
intodevelop
.$ git checkout develop $ git merge release-vX.Y.Z $ git push
-
Close the release PR.
-
Delete the release branch on Github.
-
Delete git tags for previous release (keep tags for this release for reference)
At the start of every release:
- Create an issue describing what is in the release, and pin it to the issue board, this one as an example: https://github.com/msupply-foundation/open-msupply/issues/3840
- Arrange a meeting with testers and devs to talk about:
- Release dates
- What each team is doing
- What workflows might be affected and therefore what should be prioritised for testing