diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index 1d7a1e4f..2017e9d1 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -7,85 +7,15 @@ assignees: '' --- -## Versioning +# Prepare for the Release -### How to Increment Versions - -Zebra follows [semantic versioning](https://semver.org). Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE] - -The [draft `zebrad` changelog](https://github.com/ZcashFoundation/zebra/releases) will have an automatic version bump. This version is based on [the labels on the PRs in the release](https://github.com/ZcashFoundation/zebra/blob/main/.github/release-drafter.yml). - -Check that the automatic `zebrad` version increment matches the changes in the release: - -
- -If we're releasing a mainnet network upgrade, it is a `major` release: -1. Increment the `major` version of _*all*_ the Zebra crates. -2. Increment the `patch` version of the tower crates. - -If we're not releasing a mainnet network upgrade, check for features, major changes, deprecations, and removals. If this release has any, it is a `minor` release: -1. Increment the `minor` version of `zebrad`. -2. Increment the `pre-release` version of the other crates. -3. Increment the `patch` version of the tower crates. - -Otherwise, it is a `patch` release: -1. Increment the `patch` version of `zebrad`. -2. Increment the `pre-release` version of the other crates. -3. Increment the `patch` version of the tower crates. - -Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta `pre-release` version. - -
- -### Version Locations - -Once you know which versions you want to increment, you can find them in the: - -zebrad (rc): -- [ ] zebrad `Cargo.toml` -- [ ] `README.md` -- [ ] `book/src/user/docker.md` - -crates (beta): -- [ ] zebra-* `Cargo.toml`s - -tower (patch): -- [ ] tower-* `Cargo.toml`s - -auto-generated: -- [ ] `Cargo.lock`: run `cargo build` after updating all the `Cargo.toml`s - -#### 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' '1.1.0' zebrad README.md zebra-network/src/constants.rs book/src/user/docker.md -fastmod --extensions rs,toml,md --fixed-strings '1.0.0-beta.15' '1.0.0-beta.16' zebra-* -fastmod --extensions rs,toml,md --fixed-strings '0.2.30' '0.2.31' tower-batch tower-fallback -cargo build -``` - -If you use `fastmod`, don't update versions in `CHANGELOG.md` or `zebra-dependencies-for-audit.md`. - -## README - -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 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.toml`s - -You can use a command like: -```sh - fastmod --fixed-strings '1.58' '1.65' -``` +These release steps can be done a week before the release, in separate PRs. +They can be skipped for urgent releases. ## 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](https://github.com/ZcashFoundation/zebra/blob/main/zebra-utils/README.md#zebra-checkpoints). +- [ ] You can copy the latest checkpoints from CI by following [the zebra-checkpoints README](https://github.com/ZcashFoundation/zebra/blob/main/zebra-utils/README.md#zebra-checkpoints). ## Missed Dependency Updates @@ -97,6 +27,57 @@ Here's how we make sure we got everything: - [ ] Open a separate PR with the changes - [ ] Add the output of `cargo update` to that PR as a comment + +# Make Release Changes + +These release steps can be done a few days before the release, in the same PR: +- [ ] Make sure the PRs with the new checkpoint hashes and missed dependencies are already merged + +## Versioning + +### How to Increment Versions + +Zebra follows [semantic versioning](https://semver.org). Semantic versions look like: MAJOR.MINOR.PATCH[-TAG.PRE-RELEASE] + +Choose a release level for `zebrad` based on the changes in the release that users will see: +- mainnet network upgrades are `major` releases +- 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](https://github.com/orgs/ZcashFoundation/teams/owners) + +
+ +- [ ] Update crate versions and do a release dry-run: + - [ ] `cargo release version --verbose --workspace --exclude zebrad beta` + - [ ] `cargo release version --verbose --package zebrad [ major | minor | patch ]` + - [ ] `cargo release publish --verbose --workspace --dry-run` +- [ ] Commit the version changes to your release PR branch using `git`: `cargo release commit --verbose --workspace` + +## 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 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.toml`s + +You can use a command like: +```sh +fastmod --fixed-strings '1.58' '1.65' +``` + ## Change Log **Important**: Any merge into `main` deletes any edits to the draft changelog. @@ -106,55 +87,43 @@ We use [the Release Drafter workflow](https://github.com/marketplace/actions/rel To create the final change log: - [ ] Copy the **latest** draft changelog into `CHANGELOG.md` (there can be multiple draft releases) -- [ ] Delete any trivial changes. Keep the list of those, to include in the PR +- [ ] 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 are consistent, and make sense to non-developers +- [ ] 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 +## 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](https://zcashblockexplorer.com/blocks) or other tool. +- [ ] Replace `ESTIMATED_RELEASE_HEIGHT` in [`end_of_support.rs`](https://github.com/ZcashFoundation/zebra/blob/main/zebrad/src/components/sync/end_of_support.rs) with the height you estimate the release will be tagged. +
-#### Change Categories +Optional: calculate the release tagging height -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. +- 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
-## Release support constants - -Needed for the end of support feature. Please update the following constants [in this file](https://github.com/ZcashFoundation/zebra/blob/main/zebrad/src/components/sync/end_of_support.rs): - -- [ ] `ESTIMATED_RELEASE_HEIGHT` (required) - Replace with the estimated height you estimate the release will be tagged. -
- - Find where the Zcash blockchain tip is now by using a [Zcash explorer](https://zcashblockexplorer.com/blocks) or other tool. - - Consider there are aprox `1152` blocks per day (with the current Zcash `75` seconds spacing). - - So for example if you think the release will be tagged somewhere in the next 3 days you can add `1152 * 3` to the current tip height and use that value here. -
- -## Create the Release - ### Create the Release PR -After you have the version increments, the updated checkpoints, any missed dependency updates, -and the updated changelog: - -- [ ] Make sure the PRs with the new checkpoint hashes and missed dependencies are already merged -- [ ] Push the version increments, the updated changelog and the release constants into a branch - (for example: `bump-v1.0.0` - this needs to be different to the tag name) +- [ ] Push the version increments, the updated changelog, and the release constants into a 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](https://github.com/ZcashFoundation/zebra/compare/bump-v1.0.0?expand=1&template=release-checklist.md)). - - [ ] Add the list of deleted changelog entries as a comment to make reviewing easier. - [ ] Freeze the [`batched` queue](https://dashboard.mergify.com/github/ZcashFoundation/repo/zebra/queues) using Mergify. - [ ] Mark all the release PRs as `Critical` priority, so they go in the `urgent` Mergify queue. -### 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](https://github.com/ZcashFoundation/zebra/releases) +# Release Zebra + +## 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](https://github.com/ZcashFoundation/zebra/releases) - [ ] Set the tag name to the version tag, for example: `v1.0.0` - [ ] Set the release to target the `main` branch @@ -167,23 +136,30 @@ and the updated changelog: - [ ] Publish the pre-release to GitHub using "Publish Release" - [ ] Delete all the [draft releases from the list of releases](https://github.com/ZcashFoundation/zebra/releases) -## Binary Testing +## Test the Pre-Release - [ ] Wait until the [Docker binaries have been built on `main`](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-docker.yml), 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](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-delivery.yml) + +## Publish Release + - [ ] [Publish the release to GitHub](https://github.com/ZcashFoundation/zebra/releases) by disabling 'pre-release', then clicking "Set as the latest release" + +## Publish Crates + +- [ ] Run `cargo login` +- [ ] Publish the crates to crates.io: `cargo release publish --verbose --workspace --execute` +- [ ] Check that Zebra can be installed from `crates.io`: + `cargo install --force --version 1.0.0 zebrad && ~/.cargo/bin/zebrad` + +## Publish Docker Images - [ ] Wait until [the Docker images have been published](https://github.com/ZcashFoundation/zebra/actions/workflows/release-binaries.yml) - [ ] Test the Docker image using `docker run --tty --interactive zfnd/zebra:v1.0.0`, and put the output in a comment on the PR. (You can use [gcloud cloud shell](https://console.cloud.google.com/home/dashboard?cloudshell=true)) - [ ] Un-freeze the [`batched` queue](https://dashboard.mergify.com/github/ZcashFoundation/repo/zebra/queues) using Mergify. - -## Telling Zebra Users - -- [ ] Post a summary of the important changes in the release in the `#arborist` and `#communications` Slack channels - ## Release Failures If building or running fails after tagging: @@ -191,9 +167,9 @@ If building or running fails after tagging:
1. Fix the bug that caused the failure -2. Increment the patch version again, following these instructions from the start -3. Update the code and documentation with a **new** git tag +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. Tag a **new** release +5. Follow the release checklist for the new Zebra version