9.0 KiB
name | about | title | labels | assignees |
---|---|---|---|---|
Release Checklist Template | Checklist to create and publish a Zebra release | Release Zebra (version) | A-release, C-trivial, P-Critical 🚑 |
Prepare for the Release
- Make sure there has been at least one successful full sync test since the last state change, or start a manual full sync.
- Make sure the PRs with the new checkpoint hashes and missed dependencies are already merged. (See the release ticket checklist for details)
Summarise Release Changes
These steps can be done a few days before the release, in the same PR:
Change Log
Important: Any merge into main
deletes any edits to the draft changelog.
Once you are ready to tag a release, copy the draft changelog into CHANGELOG.md
.
We use the Release Drafter workflow to automatically create a draft changelog. We follow the Keep a Changelog format.
To create the final change log:
- Copy the latest draft changelog into
CHANGELOG.md
(there can be multiple draft releases) - Delete any trivial changes
- Put the list of deleted changelog entries in a PR comment to make reviewing easier
- Combine duplicate changes
- Edit change descriptions so they will make sense to Zebra users
- Check the category for each change
- Prefer the "Fix" category if you're not sure
README
README updates can be skipped for urgent releases.
Update the README to:
- Remove any "Known Issues" that have been fixed since the last release.
- Update the "Build and Run Instructions" with any new dependencies.
Check for changes in the
Dockerfile
since the last tag:git diff <previous-release-tag> docker/Dockerfile
. - If Zebra has started using newer Rust language features or standard library APIs, update the known working Rust version in the README, book, and
Cargo.toml
s
You can use a command like:
fastmod --fixed-strings '1.58' '1.65'
Create the Release PR
- Push the updated changelog and README into a new branch
for example:
bump-v1.0.0
- this needs to be different to the tag name - Create a release PR by adding
&template=release-checklist.md
to the comparing url (Example). - Freeze the
batched
queue using Mergify. - Mark all the release PRs as
Critical
priority, so they go in theurgent
Mergify queue. - Mark all non-release PRs with
do-not-merge
, because Mergify checks approved PRs against every commit, even when a queue is frozen.
Update Versions and End of Support
Update Zebra Version
Choose a Release Level
Zebra follows semantic versioning. Semantic versions look like: MAJOR.MINOR.PATCH[-TAG.PRE-RELEASE]
Choose a release level for zebrad
. Release levels are based on user-visible changes from the changelog:
- Mainnet Network Upgrades are
major
releases - significant new features or behaviour changes; changes to RPCs, command-line, or configs; and deprecations or removals are
minor
releases - otherwise, it is a
patch
release
Zebra's Rust API doesn't have any support or stability guarantees, so we keep all the zebra-*
and tower-*
crates on a beta pre-release
version.
Update Crate Versions
If you're publishing crates for the first time, log in to crates.io, and make sure you're a member of owners group.
Check that the release will work:
- Update crate versions, commit the changes to the release branch, and do a release dry-run:
# Update everything except for alpha crates and zebrad:
cargo release version --verbose --execute --allow-branch '*' --workspace --exclude zebrad --exclude zebra-scan --exclude zebra-grpc beta
# Due to a bug in cargo-release, we need to pass exact versions for alpha crates:
cargo release version --verbose --execute --allow-branch '*' --package zebra-scan 0.1.0-alpha.4
cargo release version --verbose --execute --allow-branch '*' --package zebra-grpc 0.1.0-alpha.2
# Update zebrad:
cargo release version --verbose --execute --allow-branch '*' --package zebrad patch # [ major | minor | patch ]
# Continue with the release process:
cargo release replace --verbose --execute --allow-branch '*' --package zebrad
cargo release commit --verbose --execute --allow-branch '*'
Crate publishing is automatically checked in CI using "dry run" mode, however due to a bug in cargo-release
we need to pass exact versions to the alpha crates:
- Update
zebra-scan
andzebra-grpc
alpha crates in the release-crates-dry-run workflow script - Push the above version changes to the release branch.
Update End of Support
The end of support height is calculated from the current blockchain height:
- Find where the Zcash blockchain tip is now by using a Zcash explorer or other tool.
- Replace
ESTIMATED_RELEASE_HEIGHT
inend_of_support.rs
with the height you estimate the release will be tagged.
Optional: calculate the release tagging height
- Add
1152
blocks for each day until the release - For example, if the release is in 3 days, add
1152 * 3
to the current Mainnet block height
Update the Release PR
- Push the version increments and the release constants to the release branch.
Publish the Zebra Release
Create the GitHub Pre-Release
- Wait for all the release PRs to be merged
- Create a new release using the draft release as a base, by clicking the Edit icon in the draft release
- Set the tag name to the version tag,
for example:
v1.0.0
- Set the release to target the
main
branch - Set the release title to
Zebra
followed by the version tag, for example:Zebra 1.0.0
- Replace the prepopulated draft changelog in the release description with the final changelog you created;
starting just after the title
## [Zebra ...
of the current version being released, and ending just before the title of the previous release. - Mark the release as 'pre-release', until it has been built and tested
- Publish the pre-release to GitHub using "Publish Release"
- Delete all the draft releases from the list of releases
Test the Pre-Release
- Wait until the Docker binaries have been built on
main
, and the quick tests have passed: - Wait until the pre-release deployment machines have successfully launched
Publish Release
- Publish the release to GitHub by disabling 'pre-release', then clicking "Set as the latest release"
Publish Crates
- Run
cargo login
- Run
cargo clean
in the zebra repo (optional) - Publish the crates to crates.io:
cargo release publish --verbose --workspace --execute
- Check that Zebra can be installed from
crates.io
:cargo install --locked --force --version 1.minor.patch zebrad && ~/.cargo/bin/zebrad
and put the output in a comment on the PR.
Publish Docker Images
- Wait for the the Docker images to be published successfully.
- Un-freeze the
batched
queue using Mergify. - Remove
do-not-merge
from the PRs you added it to
Release Failures
If building or running fails after tagging:
Tag a new release, following these instructions...
- Fix the bug that caused the failure
- Start a new
patch
release - Skip the Release Preparation, and start at the Release Changes step
- Update
CHANGELOG.md
with details about the fix - Follow the release checklist for the new Zebra version