This document outlines the release process for the Babylon node (babylond)
Babylon follows semantic versioning, but with the following deviations to account for state-machine and API breaking changes.
- State-machine breaking changes & API breaking changes will result in an increase of the minor version Y (0.Y.z).
- All other changes will result in an increase of the patch version Z (0.y.Z).
A change is considered to be state-machine breaking if it requires a coordinated upgrade for the network to preserve state compatibility Note that when bumping the dependencies of Cosmos SDK and IBC, we will only treat patch releases as non state-machine breaking.
A change is considered to be API breaking if it modifies the provided API. This includes events, queries, CLI interfaces.
A release is an increment of the second number (eg: v0.1.0
→ v0.2.0
)
Note: Generally, PRs should target either main
or a long-lived feature
branch (see CONTRIBUTING.md).
- Once the team feels that
main
is feature complete, we create arelease/v0.Y.x
branch (going forward known as release branch), whereY
is the minor version number, with patch part substituted tox
(eg: v0.11.x).- PRs targeting directly a release branch can be merged only when exceptional circumstances arise.
- In the release branch
- Create a PR that adds new version section in the
CHANGELOG.md
, matching the released version e.g for branchrelease/v0.Y.x
, section will be calledv0.Y.0
- Create a PR that adds new version section in the
- We freeze the release branch from receiving any new features and focus on
releasing a release candidate.
- Finish audits and reviews.
- Add more tests.
- Fix bugs as they are discovered.
- After the team feels that the release branch works fine, we cut a release
candidate.
- Create a new annotated git tag for a release candidate in the release branch (follow the Tagging Procedure).
- The release verification on devnet must pass.
- When bugs are found, create a PR for
main
, and backport fixes to the release branch. - Before tagging the release, create and merge PR to the release branch that:
- Moves all changelog entries form
Unreleased
section of the changelog to the newly created sectionv0.Y.0
- Moves all changelog entries form
- Create new release candidate tags after bugs are fixed.
- After the team feels the release candidate is ready, create a full release:
- Note: The final release MUST have the same commit hash as the latest corresponding release candidate.
- Create a new annotated git tag in the release branch (follow the Tagging Procedure)
- After the final release is made e.g
v0.Y.0
, backport changelog changes to themain
branch- checkout a new branch from the main branch:
username/backport_changelog
- bring the new section from
release/v0.Y.x
branch to theCHANGELOG.md
file onmain
branch - open PR against the
main
branch
- checkout a new branch from the main branch:
- create a new release branch, e.g.,
release/v0.10.x
git checkout main git pull git checkout -b release/v0.10.x
- push the release branch upstream
git push
Before cutting a release (e.g., v0.10.0-rc.0
), the
following steps are necessary:
- move to the release branch, e.g.,
release/v0.10.x
git checkout release/v0.10.x
- create new tag (follow the Tagging Procedure)
Important: Always create tags from your local machine since all
release tags should be signed and annotated. Using Github UI will create a
lightweight
tag, so it's possible that babylond version
returns a commit
hash, instead of a tag. This is important because most operators build from
source, and having incorrect information when you run make install && babylond version
raises confusion.
The following steps are the default for tagging a specific branch commit using
git on your local machine. Usually, release branches are labeled release/v*
:
Ensure you have checked out the commit you wish to tag and then do (assuming
you want to release version v0.10.0-rc.0
):
git pull --tags
git tag -s -a v0.10.0-rc.0 -m "Version v0.10.0-rc.0"
A patch release is an increment of the patch number (eg: v10.0.0
→ v10.0.1
).
Important: Patch releases can break consensus only in exceptional circumstances .
Updates to the release branch should come from main
by backporting PRs
(usually done by automatic cherry pick followed by a PRs to the release branch).
The backports must be marked using backport/Y
label in PR for main.
It is the PR author's responsibility to fix merge conflicts and
ensure CI passes.
After the release branch has all commits required for the next patch release:
- Create a new annotated git tag in the release branch (follow the Tagging Procedure).