5.9 KiB
name | about | title | labels | assignees |
---|---|---|---|---|
Release Checklist Template | Checklist of versioning to create a taggable commit for Zebra |
Versioning
Which Crates to Increment
To check if any of the top-level crates need version increments, go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra and use the last modified dates of each crate. Alternatively you can use the github compare tool and check the main
branch against the last tag (Example). git diff --stat <previous-release-tag> origin/main
is also useful to see what's changed.
- Increment the crates that have new commits since the last version update
- Increment any crates that depend on crates that have changed
- Use the
zebrad
crate version in thezebra-network
user agent string - Use the latest git tag in
README.md
How to Increment Versions
Zebra follows semantic versioning.
Semantic versions look like: MAJOR
.MINOR
.PATCH[
-TAG
.PRE-RELEASE]
Pre-Release Crates
Pre-Release versions have a TAG
like "alpha" or "beta". For example: 1.0.0-alpha.0
- Increment the
PRE-RELEASE
version for the crate.
Optionally, if a MINOR
feature pre-release breaks MAJOR
API compatibility:
- Increment the
MAJOR
version, and reset all the other versions to zero
Unstable Crates
Unstable versions have a MAJOR
version of zero. For example: 0.1.0
- Follow stable crate versioning, but increment the
MINOR
version for breaking changes
Stable Crates
For example: 1.0.0
Increment the first version component in this list, and reset the other components to zero:
- MAJOR versions for breaking public API changes and removals
- check for types from dependencies that appear in the public API
- MINOR versions for new features
- PATCH versions for bug fixes
- includes dependency updates that don't impact the public API
Version Locations
Once you know which versions you want to increment, you can find them in the:
- zebra*
Cargo.toml
s - tower-*
Cargo.toml
s zebra-network
protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rsREADME.md
Cargo.lock
: automatically generated bycargo build
Merge all these version increments as one commit, by squashing and rebasing the PR onto the main branch.
After you have your changes pushed start a PR with them using this template by adding &template=release-checklist.md
to the comparing url (Example).
Version Tooling
You can use fastmod
to interactively find and replace versions.
For example, for zebra-1.0.0-alpha.12
, we did:
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.12' '1.0.0-alpha.13'
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.11' '1.0.0-alpha.12'
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.10' '1.0.0-alpha.11'
fastmod --extensions rs,toml,md --fixed-strings '0.2.9' '0.2.10' tower-batch
fastmod --extensions rs,toml,md --fixed-strings '0.2.8' '0.2.9' tower-fallback
Reviewing Version Bump Pull Requests
Check for missed changes by going to:
https://github.com/ZcashFoundation/zebra/tree/<commit-hash>/
Where <commit-hash>
is the hash of the last commit in the version bump PR.
If any Zebra or Tower crates have commit messages that are not a version bump, we have missed an update.
Also check for crates that depend on crates that have changed. They should get a version bump as well.
Initial Testing
- After any changes, test that the
cargo install
command inREADME.md
works (use--path
instead of--git
locally)
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 follow the Keep a Changelog format.
We use the Release Drafter workflow to automatically create a draft changelog.
To create the final change log:
- Copy the draft changelog into
CHANGELOG.md
- Delete any trivial changes
- 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
- Create a draft PR to update
CHANGELOG.md
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.
After merging the version update PR
- Check for any PRs that have been merged since you created the draft PR to update
CHANGELOG.md
and push any updates if necessary - Mark the PR to update
CHANGELOG.md
as "Ready for Review" - Once the changelog PR has been approved and merged, update the draft release with the final changelog
- Set the release title to
Zebra
followed by the version tag, for example:Zebra 1.0.0-alpha.0
- Set the tag name to the version tag, for example:
1.0.0-alpha.0
- Set the release to target the
main
branch - Mark the release as 'pre-release' (until we are no longer alpha/beta)
Final Testing
- After tagging the release, test that the exact
cargo install
command works (--git
behaves a bit differently to--path
)
If the build fails after tagging:
- fix the build
- check if the fixes changed any extra crates, and do the required version increments
- update
README.md
with a new git tag - update
CHANGELOG.md
with details about the fix - tag a new release