zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zebra/.github/PULL_REQUEST_TEMPLATE/release-checklist.md

6.5 KiB
Raw Blame History

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:

  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:

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

If you use fastmod, don't update versions 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