octo
/
Zebra
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

change(docs): Add publishing crates as part of release checklist (#6909) 

* change(docs): Add instructions for publishing crates as part of release checklist

* Update release-checklist.md

* Update .github/PULL_REQUEST_TEMPLATE/release-checklist.md

Co-authored-by: teor <teor@riseup.net>

* Update .github/PULL_REQUEST_TEMPLATE/release-checklist.md

Co-authored-by: teor <teor@riseup.net>

* Rewrite the release checklist using `cargo release`

* Minimise diff

* Re-order testing, minimise diff

* Add checkbox to checkpoints instruction

* Tag/promote release, then publish crates, then publish docker images

---------

Co-authored-by: teor <teor@riseup.net>
This commit is contained in:
Deirdre Connolly 2023-06-13 16:53:15 -04:00 committed by GitHub
parent 7acc04c9f4
commit d2a29b6552
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 91 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
.github/PULL_REQUEST_TEMPLATE/release-checklist.md vendored
View File

@ -7,85 +7,15 @@ assignees: ''
--- ---
## Versioning # Prepare for the Release
### How to Increment Versions These release steps can be done a week before the release, in separate PRs.
They can be skipped for urgent releases.
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:
<details>
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.
</details>
### 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 <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.toml`s
You can use a command like:
```sh
fastmod --fixed-strings '1.58' '1.65'
```
## Checkpoints ## Checkpoints
For performance and security, we want to update the Zebra checkpoints in every release. 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 ## Missed Dependency Updates
@ -97,6 +27,57 @@ Here's how we make sure we got everything:
- [ ] Open a separate PR with the changes - [ ] Open a separate PR with the changes
- [ ] Add the output of `cargo update` to that PR as a comment - [ ] 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
<details>
<summary>If you're publishing crates for the first time:</summary>
- [ ] 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)
</details>
- [ ] 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 <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.toml`s
You can use a command like:
```sh
fastmod --fixed-strings '1.58' '1.65'
```
## Change Log ## Change Log
**Important**: Any merge into `main` deletes any edits to the draft changelog. **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: To create the final change log:
- [ ] Copy the **latest** draft changelog into `CHANGELOG.md` (there can be multiple draft releases) - [ ] 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 - [ ] 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 - [ ] Check the category for each change
- Prefer the "Fix" category if you're not sure - 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.
<details> <details>
#### Change Categories <summary>Optional: calculate the release tagging height</summary>
From "Keep a Changelog": - Add `1152` blocks for each day until the release
* `Added` for new features. - For example, if the release is in 3 days, add `1152 * 3` to the current Mainnet block height
* `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.
</details> </details>
## 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.
<details>
- 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.
</details>
## Create the Release
### Create the Release PR ### Create the Release PR
After you have the version increments, the updated checkpoints, any missed dependency updates, - [ ] Push the version increments, the updated changelog, and the release constants into a branch,
and the updated changelog: for example: `bump-v1.0.0` - this needs to be different to the tag name
- [ ] 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)
- [ ] 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)). - [ ] 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. - [ ] 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. - [ ] 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, - [ ] Set the tag name to the version tag,
for example: `v1.0.0` for example: `v1.0.0`
- [ ] Set the release to target the `main` branch - [ ] 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" - [ ] 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) - [ ] 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. - [ ] 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.) (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) - [ ] 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 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) - [ ] 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`, - [ ] Test the Docker image using `docker run --tty --interactive zfnd/zebra:v1.0.0`,
and put the output in a comment on the PR. 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)) (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. - [ ] 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 ## Release Failures
If building or running fails after tagging: If building or running fails after tagging:
@ -191,9 +167,9 @@ If building or running fails after tagging:
<details> <details>
1. Fix the bug that caused the failure 1. Fix the bug that caused the failure
2. Increment the patch version again, following these instructions from the start 2. Start a new `patch` release
3. Update the code and documentation with a **new** git tag 3. Skip the **Release Preparation**, and start at the **Release Changes** step
4. Update `CHANGELOG.md` with details about the fix 4. Update `CHANGELOG.md` with details about the fix
5. Tag a **new** release 5. Follow the release checklist for the new Zebra version
</details> </details>