Release strategy - gofractally/psibase GitHub Wiki
---
title: Psibase release strategy
---
gitGraph
commit
commit
branch release-v0
commit tag: "v0.0.0"
checkout main
commit
checkout release-v0
commit id:"patch" tag:"v0.0.1"
checkout main
merge release-v0
commit
commit
checkout release-v0
merge main id: "8-b2387c3" tag: "v0.1.0"
checkout main
commit
commit
branch release-v1
commit tag: "v1.0.0"
checkout main
commit
Definitions
- Active release - The active release is the latest release. There is only one major release that is active at a time. Only the active release will have new minor releases made on it. All releases prior to the active release may only be patched.
Development
Target your feature or bugfix branches to be pulled into main
, except in the following two cases:
- Target the next release branch if and only if your current feature/bugfix does not meet the Minor Release Criteria.
- If the next release branch does not exist, you may create the next release branch.
- Target the current release branch if and only if your change is an urgent bugfix needed in the current active release.
- If you do this, you must also make an additional PR to main.
Minor release criteria
The principle is that it should not create a reason for anyone to defer upgrading to the new minor release. Usually that means:
- Low-risk
- Does not break consensus, and is otherwise backwards compatible
Creating a release
- PR to
main
an update to the Psinode and Psibase version numbers- Psinode version number lives here:
/libraries/psibase/common/include/psibase/version.hpp
- Also there’s a new field in CMakeLists.txt used for setting package versions:
set(PSIBASE_VERSION "X.Y.Z")
- Change
psibase
version number from/rust
directory using:./scripts/set-version.sh x.y.z
- Run a global search for the old version number. There are a bunch of hardcoded version numbers, especially in psibase package definitions, that
set-version
doesn’t update since they aren’t part of the mainrust/cargo/
package. - Also run a build in order to auto-generate the version number changes to
Cargo.lock
.
- Psinode version number lives here:
- From the
rust/
directory, run./scripts/publish.sh --dry-run
to gain confidence that the publish step after the final release will be successful. - Merge (directly or via pull request) from
main
to the active release branch. If the branch doesn’t yet exist, create it. - Create and push a new annotated tag (pointing at the merge commit from the previous step) using semver of the form:
vX.Y.Z
(orvX.Y.Z-pre
if it is a prerelease).
git tag -a vX.Y.Z-pre -m "psibase prerelease version vX.Y.Z”
git push origin vX.Y.Z-pre
-
A GitHub workflow will automatically detect the new tag, build Psibase, upload the artifacts to a new draft release, generate a changelog, and trigger new builds for the various Docker images.
-
Manually double-check the generated draft release in GitHub, officially release once it looks good.
- If it’s a prerelease, add the following disclaimer to the top of the changelog:
# Disclaimer This is a prerelease, and therefore there are no security or backwards compatibility guarantees. It is not recommended to use this in a production environment - use at your own risk.
- If it’s a prerelease, add the following disclaimer to the top of the changelog:
-
When you publish the release, you should publish the new rust crates using the following script from the
rust/
directory (TODO: automate this in CI/CD):./scripts/publish.sh
Creating a release branch
Branch off of main, and always create the branch of the form: release/vX
where X is the major version number.
Release schedule
For now:
- New minor release every month
- New major release whenever there are sufficiently large changes that are ready to release.
Notes & justification
This branching strategy prevents applying patches to a previous minor release. This has an important implication:
We need to ensure that we never create a reason to defer upgrading to a new minor release.
That is why we have the Minor Release Criteria.
We decided on the policy that high risk or breaking changes should target the next major release. This allows release managers to always be permitted to merge main
into the current active release. The price for this luxury is that it is possible there will be a more complicated future merge from main
into the next major release branch. But in practice, we do not expect for there to be much conflicting development between those developing for minor upgrades to the active release and those developing larger changes for the next major release.