---
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:

1. Target the next release branch if and only if your current feature/bugfix does not meet the Minor Release Criteria.
2. If the next release branch does not exist, you may create the next release branch.
3. Target the current release branch if and only if your change is an urgent bugfix needed in the current active release.
   1. 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

1. PR to main an update to the Psinode and Psibase version numbers
   1. Psinode version number lives here: /libraries/psibase/common/include/psibase/version.hpp
   2. Also there’s a new field in CMakeLists.txt used for setting package versions: set(PSIBASE_VERSION "X.Y.Z")
   3. Change psibase version number from /rust directory using: ./scripts/set-version.sh x.y.z
   4. 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 main rust/cargo/ package.
   5. Also run a build in order to auto-generate the version number changes to Cargo.lock.
2. From the rust/ directory, run ./scripts/publish.sh --dry-run to gain confidence that the publish step after the final release will be successful.
3. Merge (directly or via pull request) from main to the active release branch. If the branch doesn’t yet exist, create it.
4. Create and push a new annotated tag (pointing at the merge commit from the previous step) using semver of the form: vX.Y.Z (or vX.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

5. 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.

6. Manually double-check the generated draft release in GitHub, officially release once it looks good.

   1. 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.
      

7. 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.