Release Zebra v1.0.1

[teor2345]

Changelog Updates

• Add these new user-visible PRs to the changelog:
  • refactor(docker): allow more flexible zebra configuration #7045
  • fix: make logo fit 80 columns #7095
  • fix(legal): Use a heart image with a permissive license #7102
  • fix(hang): Stop blocking some Zebra futures for up to a minute using a CPU busy-loop, Credit: Ziggurat Team (#6763), james_katz (#7000) #7103 (release blocker)
• Check for other commits to main since #7106 on 30 June: https://github.com/ZcashFoundation/zebra/commits/main

Optional:

• add entry for fix(panic): Stop panicking on shutdown in the syncer and network init #7104 (in PR change(release): Update release script and check it in CI #7128)
• add entry for build(deps): bump tokio from 1.28.2 to 1.29.0 #7094

Prepare for the Release

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

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, large changes, deprecations, and 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:

• Install cargo-release: cargo install cargo-release
• Make sure you are an owner of the crate or a member of the Zebra crates.io owners group on GitHub

• Update crate versions, commit the changes to the release branch, and do a release dry-run:

cargo clean # optional
cargo release version --verbose --execute --workspace --exclude zebrad beta
cargo release version --verbose --execute --package zebrad patch # [ major | minor | patch ]
cargo release commit --verbose --execute
# TODO: fix missing dependency errors in cargo release, so we can do a dry run for all the crates 
cargo release publish --verbose --dry-run --workspace --exclude zebra-consensus --exclude zebra-rpc --exclude zebra-utils --exclude zebrad

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 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
  • fix(hang): Stop blocking some Zebra futures for up to a minute using a CPU busy-loop, Credit: Ziggurat Team (#6763), james_katz (#7000) #7103 (release blocker)
  • Release Zebra v1.0.1 #7090 (release preparation)
• 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.
  (You can ignore the full sync and lightwalletd tests, because they take about a day to run.)
• 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.0.1 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.
• Un-freeze the batched queue using Mergify.

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

Close #7021

[teor2345]

Trivial changes:

$ cat trivial-issues.txt | sort -u

• add(ci): Run release builds and production Docker image tests on pull requests (#7055)
• add(tests): Add snapshot tests for sprout database formats (#7057)
• build(deps): bump Swatinem/rust-cache from 2.4.0 to 2.5.0 (#7002)
• build(deps): bump baptiste0928/cargo-install from 2.0.0 to 2.1.0 (#6903)
• build(deps): bump bitflags from 2.3.1 to 2.3.2 (#6943)
• build(deps): bump clap from 4.3.3 to 4.3.4 (#6957)
• build(deps): bump clap from 4.3.4 to 4.3.5 (#7038)
• build(deps): bump clap from 4.3.5 to 4.3.6 (#7059)
• build(deps): bump clap from 4.3.6 to 4.3.8 (#7066)
• build(deps): bump docker/build-push-action from 4.1.0 to 4.1.1 (#6942)
• build(deps): bump docker/metadata-action from 4.5.0 to 4.6.0 (#6941)
• build(deps): bump hyper from 0.14.26 to 0.14.27 (#7082)
• build(deps): bump insta from 1.29.0 to 1.30.0 (#7051)
• build(deps): bump itertools from 0.10.5 to 0.11.0 (#7050)
• build(deps): bump log from 0.4.18 to 0.4.19 (#6919)
• build(deps): bump peter-evans/dockerhub-description from 3.4.1 to 3.4.2 (#7023)
• build(deps): bump reviewdog/action-actionlint from 1.37.0 to 1.37.1 (#7003)
• build(deps): bump sentry from 0.31.3 to 0.31.4 (#6958)
• build(deps): bump sentry from 0.31.4 to 0.31.5 (#6988)
• build(deps): bump serde_json from 1.0.96 to 1.0.97 (#6987)
• build(deps): bump tj-actions/changed-files from 36.1.0 to 36.2.1 (#6973)
• build(deps): bump tj-actions/changed-files from 36.2.1 to 36.3.0 (#6986)
• build(deps): bump tj-actions/changed-files from 36.3.0 to 36.4.0 (#7004)
• build(deps): bump tj-actions/changed-files from 36.4.0 to 36.4.1 (#7024)
• build(deps): bump tj-actions/changed-files from 36.4.1 to 37.0.3 (#7065)
• build(deps): bump w9jds/firebase-action from 11.30.1 to 12.4.0 (#7005)
• change(commands): Ignore error from loading config if running the 'generate' or 'download' commands (#7014)
• change(docs): Add cargo clean step to crate publishing steps (#6959)
• change(docs): Explicitly invoke --execute when bumping crate versions (#6949)
• change(network): Configurable maximum connections per IP (#7013)
• change(release): Add deny.toml update details to release-checklist.md (#7042)
• change(release): Add more cargo clean to the release checklist (#6964)
• change(release): Change network upgrade wording in release-checklist.md (#7010)
• change(rename): Update missed tower-batch-control renames (#7011)
• change(state): Use OrderedUtxo in CheckpointVerifiedBlock (#6971)
• cleanup(test): Make test debugging output more readable (#7027)
• cleanup(workflow): Remove an outdated TODO in release-binaries.yml (#6978)
• fix(build): Suppress warnings about doc links pointing to private items (#6944)
• fix(cd): Rename a CD job with the same name as a CI job (#7063)
• fix(changelog): Fix a broken link in CHANGELOG.md (#6979)
• fix(cleanup): redundant configuration feature (#6929)
• fix(deps): Replace openssl with rustls in tests and experimental features (#7047)
• fix(doc): Add fastmod --hidden to mass-renames.md (#6913)
• fix(docker): Improve Dockerfile cache use by making build commands match exactly (#6933)
• fix(docker): Stop resetting the cargo-chef cache in the Dockerfile (#6934)
• fix(logs): Avoid grouping logs for separate tasks (#6923)
• fix(net): Clean up licensing, closure move, log typos, tracing spans (#6995)
• fix(release): Use correct cargo release manifest key name (#7028)
• fix(state): Replace a chain length assertion with a NotReadyToBeCommitted error (#7072)
• refactor(app): De-duplicate and fix version handling code (#6996)
• refactor(consensus): Rename router_verifier to block_verifier_router (#6998)
• rename(state): do additional renaming for clarification purposes (#6967)
• Refactor the structure of finalizable blocks, to make validation clearer (#7035, #7025)

[teor2345]

• 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

This step was done in PR #7032.

[teor2345]

This is the draft changelog as of commit caf9a09 at Wednesday 28 June 0100 UTC.

[arya2]

The changelog looks good to me, it's currently only missing #7045.

[codecov]

Codecov Report

Merging #7090 (70418bc) into main (2a31972) will decrease coverage by 0.16%.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7090      +/-   ##
==========================================
- Coverage   77.49%   77.34%   -0.16%     
==========================================
  Files         310      310              
  Lines       41795    41795              
==========================================
- Hits        32390    32327      -63     
- Misses       9405     9468      +63     

[arya2]

The changelog and version bumps look good, and I agree with updating zebrad's patch version.

CI panicked in wait_for_zebra_checkpoints_generation(): https://github.com/ZcashFoundation/zebra/actions/runs/5418491535/jobs/9851372930?pr=7090#step:8:219

[teor2345]

$ cargo install --locked --force --version 1.0.1 zebrad
Downloaded zebrad v1.0.1
Downloaded 1 crate (231.9 KB) in 1.72s
Updating crates.io index
Installing zebrad v1.0.1
Updating crates.io index
warning: package `x25519-dalek v2.0.0-rc.2` in Cargo.lock is yanked in registry `crates-io`, consider running without --locked
Updating crates.io index
Compiling proc-macro2 v1.0.60
Compiling quote v1.0.28
...
   Compiling zebrad v1.0.1
   Compiling zcash_primitives v0.11.0
   Compiling zebra-chain v1.0.0-beta.27
   Compiling zcash_proofs v0.11.0
   Compiling zebra-node-services v1.0.0-beta.27
   Compiling zebra-network v1.0.0-beta.27
   Compiling zebra-script v1.0.0-beta.27
   Compiling rocksdb v0.21.0
   Compiling zebra-state v1.0.0-beta.27
   Compiling zebra-consensus v1.0.0-beta.27
   Compiling zebra-rpc v1.0.0-beta.27
    Finished release [optimized + debuginfo] target(s) in 3m 00s
   Replacing /home/dev/.cargo/bin/zebrad
    Replaced package `zebrad v1.0.0` with `zebrad v1.0.1` (executable `zebrad`)

$ ~/.cargo/bin/zebrad