7.8 KiB
name | about | title | labels | assignees |
---|---|---|---|---|
Release Checklist Template | Checklist of versioning to create a taggable commit for Zebra |
Versioning
How to Increment Versions
Zebra follows semantic versioning.
Semantic versions look like: MAJOR.
MINOR.
PATCH[-
TAG.
PRE-RELEASE]
The draft zebrad
changelog will have an automatic version bump. This version is based on the labels on the PRs in the release.
Check that the automatic zebrad
version increment is correct:
If we're releasing a mainnet network upgrade, it is a major
release:
- Increment the
major
version of all the Zebra crates. - Increment the
patch
version of the tower crates.
If we're not releasing a mainnet network upgrade, check for features, major changes, deprecations, and removals. If this release has any, it is a minor
release:
- Increment the
minor
version ofzebrad
. - Increment the
pre-release
version of the other crates. - Increment the
patch
version of the tower crates.
Otherwise, it is a patch
release:
- Increment the
patch
version ofzebrad
. - Increment the
pre-release
version of the other crates. - Increment the
patch
version of the tower crates.
Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta pre-release
version.
Version Locations
Once you know which versions you want to increment, you can find them in the:
zebrad (rc):
- zebrad
Cargo.toml
zebra-network
protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rsREADME.md
book/src/user/docker.md
crates (pre-release):
- zebra-*
Cargo.toml
s
tower (patch):
- tower-*
Cargo.toml
s
auto-generated:
Cargo.lock
: runcargo build
after updating all theCargo.toml
s
Version Tooling
You can use fastmod
to interactively find and replace versions.
For example, you can do something like:
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-rc.0' '1.0.0-rc.1' zebrad README.md zebra-network/src/constants.rs
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-beta.15' '1.0.0-beta.16' zebra-*
fastmod --extensions rs,toml,md --fixed-strings '0.2.30' '0.2.31' tower-batch tower-fallback
If you use fastmod
, don't update versions in CHANGELOG.md
or zebra-dependencies-for-audit.md
.
README
Update the README to:
- Remove any "Known Issues" that have been fixed
- 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
.
Checkpoints
With every release and for performance reasons, we want to update the zebra checkpoints. More information on how to do this can be found in the zebra-checkpoints README.
To do this you will need a synchronized zcashd
node. You can request help from other zebra team members to submit this PR if you can't make it yourself at the moment of the release.
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. Keep the list of those, to include in the PR
- Combine duplicate changes
- Edit change descriptions so they are consistent, and make sense to non-developers
- Check the category for each change
- Prefer the "Fix" category if you're not sure
Change Categories
From "Keep a Changelog":
Added
for new features.Changed
for changes in existing functionality.Deprecated
for soon-to-be removed features.Removed
for now removed features.Fixed
for any bug fixes.Security
in case of vulnerabilities.
Create the Release
Create the Release PR
After you have the version increments, the updated checkpoints and the updated changelog:
- Make sure the PR with the new checkpoint hashes is already merged, or make it part of the changelog PR
- Push the version increments and the updated changelog into a branch
(for example:
bump-v1.0.0-rc.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).- Add the list of deleted changelog entries as a comment to make reviewing easier.
- Turn on Merge Freeze.
- Once the PR is ready to be merged, unfreeze it here. Do not unfreeze the whole repository.
- Update the PR to the latest
main
branch using@mergifyio update
. Then Mergify should merge it in-place. If it makes a merge PR instead, that PR will get cancelled by the merge freeze. So just merge the changelog PR manually.
Create the Release
- Once the PR has been 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-rc.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-rc.0
- Replace the prepopulated draft changelog in the release description by 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
Binary Testing
- Wait until the Docker binaries have been built on
main
, and the quick tests have passed. (You can ignore the full sync andlightwalletd
tests, because they take about a day to run.) - Publish the release to GitHub by disabling 'pre-release', then clicking "Set as the latest release"
- Wait until the Docker images have been published
- Test the Docker image using
docker run --tty --interactive zfnd/zebra:1.0.0-rc.<version>
- Turn off Merge Freeze for the whole repository
Blog Post
If the release contains new features (major
or minor
), or high-priority bug fixes:
- Ask the team about doing a blog post
If building or running fails after tagging:
- Fix the bug that caused the failure
- Increment versions again, following these instructions from the start
- Update the code and documentation with a new git tag
- Update
CHANGELOG.md
with details about the fix - Tag a new release