zebra/.github/PULL_REQUEST_TEMPLATE/release-checklist.md

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 the zebra-network user agent string (currently the constant USER_AGENT in zebra-network/src/constants.rs)
• 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

1. Increment the PRE-RELEASE version for the crate.

Optionally, if a MINOR feature pre-release breaks MAJOR API compatibility:

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

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

1. MAJOR versions for breaking public API changes and removals
   • check for types from dependencies that appear in the public API
2. MINOR versions for new features
3. 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.tomls
• tower-* Cargo.tomls
• zebra-network protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rs
• README.md
• Cargo.lock: automatically generated by cargo 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 in works. Use e.g. cargo install --locked --path zebrad.

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 in README.md works (--git behaves a bit differently to --path)

If the build fails after tagging:

1. fix the build
2. check if the fixes changed any extra crates, and do the required version increments
3. update README.md with a new git tag
4. update CHANGELOG.md with details about the fix
5. tag a new release