Release Zebra 1.0.0-beta.12

[teor2345]

Related Tickets

Close #4651

Depends-On: #4680

Versioning

Which Crates to Increment

To check if any of the top-level crates need version increments:

1. go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra
2. check if the last commit was a Zebra version bump, or something else

Alternatively you can:

• use the github compare tool and check the main branch against the last tag (Example)
• use git diff --stat <previous-release-tag> origin/main

Once you know which crates have changed:

• Increment the crates that have new commits since the last version update
• Increment any crates that depend on crates that have changed
• Keep a list of the crates that haven't been incremented, to include in the PR

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.

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

Reviewing Version Bumps

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.

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
• book/src/user/install.md
• Cargo.lock: automatically generated by cargo build

Version Tooling

You can use fastmod to interactively find and replace versions.

For example, you can do something like:

fastmod --extensions rs,toml,md --fixed-strings '1.0.0-beta.11' '1.0.0-beta.12'
fastmod --extensions rs,toml,md --fixed-strings '0.2.26' '0.2.27' tower-batch tower-fallback

Ignore any fastmod updates to previous release notes in CHANGELOG.md.

README

We should update the README to:

• remove any "Known Issues" that have been fixed
• 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.

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. Keep the list of those, to include in the PR
• 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

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.

Create the Release

Create the Release PR

After you have the version increments and the updated changelog:

• Push the version increments and the updated changelog into a branch
  (name suggestion, example: v1.0.0-alpha.0-release)
• Create a release PR by adding &template=release-checklist.md to the
  comparing url (Example).
  • Add the list of deleted changelog entries as a comment to make reviewing easier.
  • Also add the list of not-bumped crates as a comment (can use the same comment as the previous one).
• Turn on Merge Freeze.
• Once the PR is ready to be merged, unfreeze it here.
  Do not unfreeze the whole repository.

Create the Release

• Once the PR has been 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-alpha.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-alpha.0
• Copy the final changelog of this release to the release description
  (starting just after the title ## [Zebra ...)
• Mark the release as 'pre-release' (until we are no longer alpha/beta)
• Publish the release

Final Testing

• After tagging the release, test that the exact cargo install command in README.md works
  (--git behaves a bit differently to --path)
• Turn off Merge Freeze for the whole repository

If the build fails after tagging:

1. fix the build
2. increment versions again, following these instructions from the start
3. update README.md with a new git tag
4. update CHANGELOG.md with details about the fix
5. tag a new release

[teor2345]

Notes for reviewers:

I bumped all the crate versions.
I made tower-fallback the same version as tower-batch to simplify future version updates.

I deleted almost all the dependency version bumps (there were a lot).
I also deleted some trivial documentation changes, and merged some docs into the related PR's changelog entry.

[codecov]

Codecov Report

Merging #4714 (8485180) into main (2103f36) will decrease coverage by 0.11%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #4714      +/-   ##
==========================================
- Coverage   78.90%   78.78%   -0.12%     
==========================================
  Files         306      306              
  Lines       37537    37537              
==========================================
- Hits        29618    29573      -45     
- Misses       7919     7964      +45     

[conradoplg]

Looks good!