chore(release): Zebra v4.2.0

[oxarbitrage]

---

name: 'Release Checklist Template'
about: 'Checklist to create and publish a Zebra release'
title: 'Release Zebra (version)'
labels: 'A-release, C-exclude-from-changelog, 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.

Checkpoints

For performance and security, we want to update the Zebra checkpoints in every release.

• You can copy the latest checkpoints from CI by following the zebra-checkpoints README.

Missed Dependency Updates

Sometimes dependabot misses some dependency updates, or we accidentally turned them off.

This step can be skipped if there is a large pending dependency upgrade. (For example, shared ECC crates.)

Here's how we make sure we got everything:

• Run cargo update on the latest main branch, and keep the output
• If needed, add duplicate dependency exceptions to deny.toml
• If needed, remove resolved duplicate dependencies from deny.toml
• Open a separate PR with the changes
• Add the output of cargo update to that PR as a comment

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-dependencies to run.

Zebra git sources dependencies

• Ensure the check-no-git-dependencies 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

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

Update Crate Versions and Crate Change Logs

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:

• Determine which crates require release. Run git diff --stat <previous_tag>
  and enumerate the crates that had changes.
• Update (or install) semver-checks: cargo +stable install cargo-semver-checks --locked
• Update (or install) public-api: cargo +stable install cargo-public-api --locked
• For each crate that requires a release:
  • Determine which type of release to make. Run semver-checks to list API
    changes: cargo semver-checks -p <crate> --default-features. If there are
    breaking API changes, do a major release, or try to revert the API change
    if it was accidental. Otherwise do a minor or patch release depending on
    whether a new API was added. Note that semver-checks won't work
    if the previous realase was yanked; you will have to determine the
    type of release manually.
  • Update the crate CHANGELOG.md listing the API changes or other
    relevant information for a crate consumer. Use public-api to list all
    API changes: cargo public-api diff latest -p <crate> -sss. You can use
    e.g. copilot to turn it into a human-readable list, e.g. (write the output
    to api.txt beforehand):
    copilot -p "Transform @api.txt which is a API diff into a human-readable description of the API changes. Be terse. Write output api-readable.txt. Use backtick quotes for identifiers. Use '### Breaking Changes' header for changes and removals, and '### Added' for additions. Make each item start with a verb e.g, Added, Changed" --allow-tool write
    It might also make sense to copy entries from the zebrad changelog.
  • Update crate versions:

cargo release version --verbose --execute --allow-branch '*' -p <crate> patch # [ major | minor ]
cargo release replace --verbose --execute --allow-branch '*' -p <crate>

• Commit and 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

• Find where the Zcash blockchain tip is now by using a Zcash Block Explorer or other tool.
• 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:
  • zfnd-ci-integration-tests-gcp.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
• It is recommended that the following step be run from a fresh checkout of
  the repo, to avoid accidentally publishing files like e.g. logs that might
  be lingering around
• Publish the crates to crates.io; edit the list to only include the crates that
  have been changed, but keep their overall order:

for c in zebra-test tower-fallback zebra-chain tower-batch-control zebra-node-services zebra-script zebra-state zebra-consensus zebra-network zebra-rpc zebra-utils zebrad; do cargo release publish --verbose --execute -p $c; done

• Check that Zebra can be installed from crates.io:
  cargo install --locked --force --version <version> 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...

1. Fix the bug that caused the failure
2. Start a new patch release
3. Skip the Release Preparation, and start at the Release Changes step
4. Update CHANGELOG.md with details about the fix
5. Follow the release checklist for the new Zebra version

[oxarbitrage]

Excluded TODO: put this in a PR comment, not the CHANGELOG

• add(CI): Setup zebra build env (#10375)
• add: agent-shell directory to .gitignore (#10381)
• build(deps): bump the devops group across 1 directory with 8 updates (#10345)
• fix(release): Links in release issue (#10384)
• release(changelog): Add changelogs for OpenRPC changes (#10326)

Excluded manually:

• chore: update CHANGELOGs to reflect changes made in #10056 and #9979 (#10273)
• cleanup(docs): Remove already fixed TODO left by #10314 (#10368)
• docs: Fix package installation command for Redis (#10299)
• docs: Update zebra grafana dashboards path in metrics.md (#10330)
• fix(docs): Markdown lint in state changelog (#10367)
• ci: make test-docker more robust by adjusting grep pattern (#10291)
• fix(tests): wait for process termination and use read-only state init (#10263)

[upbqdn]

#10398 fixes the failing CI.

[upbqdn]

The changelogs look good. It might be worth changing "Breaking Changes" to "Changed" for consistency with what we already have.

It would also be good to have @conradoplg's review of them.

requested changes not needed in the end

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-03-13 11:11 UTC · Rule: urgent
• ✅ Checks passed · in-place
• ✅ Merged — 2026-03-13 11:14 UTC · at c4d2df0a2c1fb48903dad2043cacefbd46a61a4d

This pull request spent 2 minutes 26 seconds in the queue, including 1 second running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • chore(release): Zebra v4.2.0 #10389
• #approved-reviews-by >= 1 [🛡 GitHub repository ruleset rule PR Requirements]
  • chore(release): Zebra v4.2.0 #10389
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • chore(release): Zebra v4.2.0 #10389
• #changes-requested-reviews-by = 0 [🛡 GitHub repository ruleset rule PR Requirements]
  • chore(release): Zebra v4.2.0 #10389
• #review-threads-unresolved = 0 [🛡 GitHub repository ruleset rule PR Requirements]
  • chore(release): Zebra v4.2.0 #10389
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = test crate build success
  • check-neutral = test crate build success
  • check-skipped = test crate build success
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = lint success
  • check-neutral = lint success
  • check-skipped = lint success
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = test success
  • check-neutral = test success
  • check-skipped = test success