chore(release): Zebra release v2.2.0 #9195

oxarbitrage · 2025-02-03T10:45:53Z

name: 'Release Checklist Template'
about: 'Checklist to create and publish a Zebra release'
title: 'Release Zebra (version)'
labels: 'A-release, C-trivial, P-Critical 🚑'
assignees: ''

Prepare for the Release

Make sure there has been at least one successful full sync test in the main branch 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.tomls

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 the urgent 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.
Add the A-release tag to the release pull request in order for the check_no_git_refs_in_cargo_lock to run.

Zebra git sources dependencies

Ensure the check_no_git_refs_in_cargo_lock check passes.

This check runs automatically on pull requests with the A-release label. It must pass for crates to be published to crates.io. If the check fails, you should either halt the release process or proceed with the understanding that the crates will not be published on crates.io.

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 '*'

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 Block Explorer or other tool.
Replace ESTIMATED_RELEASE_HEIGHT in end_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:
- ci-tests.yml
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.
Wait for the new tag in the dockerhub zebra space
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

oxarbitrage · 2025-02-03T10:54:29Z

pull requests out of the changelog:


- Update copyright year to 2025 ([#9127](https://github.com/ZcashFoundation/zebra/pull/9127))
- fix: fix RUSTSEC-2024-0402 ([#9141](https://github.com/ZcashFoundation/zebra/pull/9141))
- fix: fix typos ([#9140](https://github.com/ZcashFoundation/zebra/pull/9140))
- fix: typos with `address` ([#9134](https://github.com/ZcashFoundation/zebra/pull/9134))
- fix(ci): Remove the `release crates` workflow ([#9120](https://github.com/ZcashFoundation/zebra/pull/9120))
- fix(workflows): update patch jobs conditions and naming ([#9117](https://github.com/ZcashFoundation/zebra/pull/9117))
- refactor(workflows): avoid using cached states for release instances ([#9137](https://github.com/ZcashFoundation/zebra/pull/9137))
- fix(workflows): update patch jobs conditions and naming ([#9117](https://github.com/ZcashFoundation/zebra/pull/9117))
- feat(actions): use GitHub `environments` for infra deployments ([#9003](https://github.com/ZcashFoundation/zebra/pull/9003))


- Docs: fix typos in documentation files ([#9153](https://github.com/ZcashFoundation/zebra/pull/9153))
- Run dependabot monthly instead of weekly ([#9171](https://github.com/ZcashFoundation/zebra/pull/9171))
- build(deps): bump codecov/codecov-action from 5.1.2 to 5.2.0 in the devops group ([#9155](https://github.com/ZcashFoundation/zebra/pull/9155))
- build(deps): bump docker/build-push-action from 6.11.0 to 6.12.0 in the devops group ([#9125](https://github.com/ZcashFoundation/zebra/pull/9125))
- build(deps): bump the devops group across 1 directory with 4 updates ([#9091](https://github.com/ZcashFoundation/zebra/pull/9091))
- build(deps): bump the devops group across 1 directory with 5 updates ([#9109](https://github.com/ZcashFoundation/zebra/pull/9109))
- build(deps): bump the devops group with 2 updates ([#9174](https://github.com/ZcashFoundation/zebra/pull/9174))
- build(deps): bump the ecc group across 1 directory with 3 updates ([#9092](https://github.com/ZcashFoundation/zebra/pull/9092))
- build(deps): bump the prod group across 1 directory with 22 updates ([#9065](https://github.com/ZcashFoundation/zebra/pull/9065))
- build(deps): bump the prod group across 1 directory with 36 updates ([#9179](https://github.com/ZcashFoundation/zebra/pull/9179))
- build(deps): bump the prod group with 10 updates ([#9077](https://github.com/ZcashFoundation/zebra/pull/9077))
- chore(checkpoints): Update the mainnet and testnet checkpoints for v2.2.0 ([#9180](https://github.com/ZcashFoundation/zebra/pull/9180))
- chore: Fix new clippy lints ([#9114](https://github.com/ZcashFoundation/zebra/pull/9114))
- chore: delete repetitive words ([#9131](https://github.com/ZcashFoundation/zebra/pull/9131))
- docs: corrections ([#9189](https://github.com/ZcashFoundation/zebra/pull/9189))
- feat(actions): use GitHub `environments` for infra deployments ([#9003](https://github.com/ZcashFoundation/zebra/pull/9003))
- fix spelling issues  ([#9177](https://github.com/ZcashFoundation/zebra/pull/9177))
- fix(ci): Remove the `release crates` workflow ([#9120](https://github.com/ZcashFoundation/zebra/pull/9120))
- fix(consensus): Avoid a concurrency bug when verifying transactions in blocks that are already present in the mempool ([#9118](https://github.com/ZcashFoundation/zebra/pull/9118))
- fix(consensus): Verify consensus branch ID in SIGHASH precomputation ([#9139](https://github.com/ZcashFoundation/zebra/pull/9139))
- fix(test): Fixes bugs in the lightwalletd integration tests ([#9052](https://github.com/ZcashFoundation/zebra/pull/9052))
- fix(workflows): update patch jobs conditions and naming ([#9117](https://github.com/ZcashFoundation/zebra/pull/9117))
- refactor(workflows): avoid using cached states for release instances ([#9137](https://github.com/ZcashFoundation/zebra/pull/9137))
- release(maintenance): Run cargo update for v2.2.0 ([#9188](https://github.com/ZcashFoundation/zebra/pull/9188))

conradoplg

Looks good

CHANGELOG.md

Co-authored-by: Conrado Gouvea <[email protected]>

oxarbitrage · 2025-02-04T21:22:14Z

All crate versions were published to crates.io, but the command we are using in the release template failed, so i think it worth to add a note here about that.

When i used cargo release publish --verbose --workspace --execute as suggested by the template i got the following list of crates to update:

Publish
  zebra-test 1.0.0-beta.45
  zebra-chain 1.0.0-beta.45
  tower-batch-control 0.2.41-beta.21
  tower-fallback 0.2.41-beta.21
  zebra-node-services 1.0.0-beta.45
  zebra-script 1.0.0-beta.45
  zebra-state 1.0.0-beta.45
  zebra-consensus 1.0.0-beta.45
  zebra-network 1.0.0-beta.45
  zebra-rpc 1.0.0-beta.45
  zebra-utils 1.0.0-beta.45
  zebrad 2.2.0
  zebra-grpc 0.1.0-alpha.12
  zebra-scan 0.1.0-alpha.14
? [y/N]

That is ok, however, the publication fails at the tower-batch-control crate. This is because tower-fallback needs to be published first. Similar with zebrad, it fails because zebra-grpc needs to go first.

The solution was to update crate by crate in an acceptable order:

...
cargo release publish --verbose -p zebra-fallback --execute
cargo release publish --verbose -p tower-batch-control --execute
...
cargo release publish --verbose -p zebra-grpc --execute
cargo release publish --verbose -p zebrad --execute
cargo release publish --verbose -p zebra-scan --execute

List of bumped crates:

oxarbitrage added 2 commits February 2, 2025 15:28

add changelog section for 2.2.0

07c8c37

chore: Release

d6d02f7

oxarbitrage requested review from a team as code owners February 3, 2025 10:45

oxarbitrage requested review from arya2 and upbqdn and removed request for a team February 3, 2025 10:45

github-actions bot added the C-trivial Category: A trivial change that is not worth mentioning in the CHANGELOG label Feb 3, 2025

oxarbitrage temporarily deployed to dev February 3, 2025 10:46 — with GitHub Actions Inactive

oxarbitrage added A-release Area: Zebra releases and release management P-Critical 🚑 labels Feb 3, 2025

oxarbitrage temporarily deployed to dev February 3, 2025 10:53 — with GitHub Actions Inactive

oxarbitrage temporarily deployed to dev February 3, 2025 10:54 — with GitHub Actions Inactive

update end of support

d019669

oxarbitrage temporarily deployed to dev February 3, 2025 11:14 — with GitHub Actions Inactive

oxarbitrage temporarily deployed to dev February 3, 2025 11:21 — with GitHub Actions Inactive

oxarbitrage temporarily deployed to dev February 4, 2025 11:26 — with GitHub Actions Inactive

conradoplg previously approved these changes Feb 4, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Update CHANGELOG.md

715b8c8

Co-authored-by: Conrado Gouvea <[email protected]>

oxarbitrage dismissed conradoplg’s stale review via 715b8c8 February 4, 2025 14:29

oxarbitrage temporarily deployed to dev February 4, 2025 14:30 — with GitHub Actions Inactive

oxarbitrage temporarily deployed to dev February 4, 2025 14:37 — with GitHub Actions Inactive

arya2 approved these changes Feb 4, 2025

View reviewed changes

mergify bot added a commit that referenced this pull request Feb 4, 2025

Merge of #9195

01bbbc6

mergify bot mentioned this pull request Feb 4, 2025

merge queue: embarking main (6f24c9c) and #9195 together #9203

Closed

mergify bot merged commit 6d01f05 into main Feb 4, 2025
202 checks passed

mergify bot deleted the bump-v2.2.0 branch February 4, 2025 16:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(release): Zebra release v2.2.0 #9195

chore(release): Zebra release v2.2.0 #9195

oxarbitrage commented Feb 3, 2025 •

edited

Loading

oxarbitrage commented Feb 3, 2025

conradoplg left a comment

oxarbitrage commented Feb 4, 2025

chore(release): Zebra release v2.2.0 #9195

chore(release): Zebra release v2.2.0 #9195

Conversation

oxarbitrage commented Feb 3, 2025 • edited Loading

Prepare for the Release

Summarise Release Changes

Change Log

README

Create the Release PR

Zebra git sources dependencies

Update Versions and End of Support

Update Zebra Version

Choose a Release Level

Update Crate Versions

Update End of Support

Update the Release PR

Publish the Zebra Release

Create the GitHub Pre-Release

Test the Pre-Release

Publish Release

Publish Crates

Publish Docker Images

Release Failures

oxarbitrage commented Feb 3, 2025

conradoplg left a comment

Choose a reason for hiding this comment

oxarbitrage commented Feb 4, 2025

oxarbitrage commented Feb 3, 2025 •

edited

Loading