2021-02-09 16:56:58 -08:00
---
name: Release Checklist Template
about: Checklist of versioning to create a taggable commit for Zebra
title: ''
labels:
assignees: ''
---
## Versioning
2022-09-27 05:41:55 -07:00
### How to Increment Versions
2021-02-09 16:56:58 -08:00
2022-09-27 05:41:55 -07:00
Zebra follows [semantic versioning ](https://semver.org ).
2022-10-05 05:46:10 -07:00
Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]
2022-07-07 13:31:19 -07:00
2022-10-05 05:46:10 -07:00
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 ).
2022-07-07 13:31:19 -07:00
2022-09-27 05:41:55 -07:00
Check that the automatic `zebrad` version increment is correct:
2022-09-27 14:53:00 -07:00
2022-10-05 05:46:10 -07:00
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.
2022-09-27 14:53:00 -07:00
2022-10-05 05:46:10 -07:00
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.
2022-09-27 14:53:00 -07:00
2022-10-05 05:46:10 -07:00
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.
2022-09-27 14:53:00 -07:00
2022-10-05 05:46:10 -07:00
Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta `pre-release` version.
2022-09-27 14:53:00 -07:00
2021-02-09 16:56:58 -08:00
### Version Locations
Once you know which versions you want to increment, you can find them in the:
2022-10-05 05:46:10 -07:00
zebrad (rc):
- [ ] zebrad `Cargo.toml`
2021-02-09 16:56:58 -08:00
- [ ] `zebra-network` protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rs
- [ ] `README.md`
2022-10-31 22:47:37 -07:00
- [ ] `book/src/user/docker.md`
2022-10-05 05:46:10 -07:00
crates (pre-release):
- [ ] zebra-* `Cargo.toml` s
tower (patch):
- [ ] tower-* `Cargo.toml` s
auto-generated:
2022-09-27 14:53:00 -07:00
- [ ] `Cargo.lock` : run `cargo build` after updating all the `Cargo.toml` s
2021-02-09 16:56:58 -08:00
2021-02-22 23:31:02 -08:00
#### Version Tooling
You can use `fastmod` to interactively find and replace versions.
2021-12-21 12:13:26 -08:00
For example, you can do something like:
2021-02-22 23:31:02 -08:00
```
2022-10-31 15:29:26 -07:00
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-rc.0' '1.0.0-rc.1' zebrad README.md zebra-network/src/constants.rs
2022-10-05 05:46:10 -07:00
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
2021-02-22 23:31:02 -08:00
```
2022-12-05 10:50:37 -08:00
If you use `fastmod` , don't update versions in `CHANGELOG.md` or `zebra-dependencies-for-audit.md` .
2021-05-12 01:42:48 -07:00
2021-11-02 08:36:47 -07:00
## README
2022-10-05 05:46:10 -07:00
Update the README to:
2022-07-07 13:31:19 -07:00
- [ ] 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` .
2021-03-22 21:39:12 -07:00
2022-07-20 20:44:40 -07:00
## Checkpoints
With every release and for performance reasons, we want to update the zebra checkpoints. More information on how to do this can be found in [the zebra-checkpoints README ](https://github.com/ZcashFoundation/zebra/blob/main/zebra-consensus/src/checkpoint/README.md ).
To do this you will need a synchronized `zcashd` node. You can request help from other zebra team members to submit this PR if you can't make it yourself at the moment of the release.
2021-02-09 16:56:58 -08:00
## Change Log
2022-07-07 13:31:19 -07:00
**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` .
2021-03-16 17:24:16 -07:00
2021-02-09 16:56:58 -08:00
We use [the Release Drafter workflow ](https://github.com/marketplace/actions/release-drafter ) to automatically create a [draft changelog ](https://github.com/ZcashFoundation/zebra/releases ).
2022-10-05 05:46:10 -07:00
We follow the [Keep a Changelog ](https://keepachangelog.com/en/1.0.0/ ) format.
2021-02-09 16:56:58 -08:00
To create the final change log:
2021-06-22 06:31:30 -07:00
- [ ] Copy the draft changelog into `CHANGELOG.md`
2022-02-23 10:18:30 -08:00
- [ ] Delete any trivial changes. Keep the list of those, to include in the PR
2021-02-09 16:56:58 -08:00
- [ ] Combine duplicate changes
- [ ] Edit change descriptions so they are consistent, and make sense to non-developers
- [ ] Check the category for each change
2022-07-07 13:31:19 -07:00
- Prefer the "Fix" category if you're not sure
2021-02-09 16:56:58 -08:00
2022-07-07 13:31:19 -07:00
< details >
2022-10-05 05:46:10 -07:00
2021-02-09 16:56:58 -08:00
#### 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.
2022-07-07 13:31:19 -07:00
< / details >
2022-04-05 11:06:46 -07:00
## Create the Release
2021-12-23 05:16:15 -08:00
2022-04-05 11:06:46 -07:00
### Create the Release PR
2022-07-20 20:44:40 -07:00
After you have the version increments, the updated checkpoints and the updated changelog:
2021-12-23 05:16:15 -08:00
2022-10-05 05:46:10 -07:00
- [ ] Make sure the PR with the new checkpoint hashes is already merged, or make it part of the changelog PR
2021-12-23 05:16:15 -08:00
- [ ] Push the version increments and the updated changelog into a branch
2022-11-02 17:28:46 -07:00
(for example: `bump-v1.0.0-rc.0` - this needs to be different to the tag name)
2021-12-23 05:16:15 -08:00
- [ ] Create a release PR by adding `&template=release-checklist.md` to the
2022-11-02 17:28:46 -07:00
comparing url ([Example](https://github.com/ZcashFoundation/zebra/compare/v1.0.0-rc.0-release?expand=1& template=release-checklist.md)).
2022-07-07 13:31:19 -07:00
- [ ] Add the list of deleted changelog entries as a comment to make reviewing easier.
2022-06-03 17:59:42 -07:00
- [ ] Turn on [Merge Freeze ](https://www.mergefreeze.com/installations/3676/branches ).
2022-07-07 13:31:19 -07:00
- [ ] Once the PR is ready to be merged, unfreeze it [here ](https://www.mergefreeze.com/installations/3676/branches ).
Do not unfreeze the whole repository.
2022-04-05 11:06:46 -07:00
### Create the Release
2022-10-05 05:46:10 -07:00
- [ ] Once the PR has been merged, create a new release using the draft release as a base,
2022-07-07 13:31:19 -07:00
by clicking the Edit icon in the [draft release ](https://github.com/ZcashFoundation/zebra/releases )
- [ ] Set the tag name to the version tag,
2022-10-05 05:46:10 -07:00
for example: `v1.0.0-rc.0`
2022-06-13 14:26:58 -07:00
- [ ] Set the release to target the `main` branch
2022-07-07 13:31:19 -07:00
- [ ] Set the release title to `Zebra ` followed by the version tag,
2022-10-05 05:46:10 -07:00
for example: `Zebra 1.0.0-rc.0`
2022-09-02 01:55:09 -07:00
- [ ] Replace the prepopulated draft changelog in the release description by 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.
2022-09-27 14:53:00 -07:00
- [ ] Mark the release as 'pre-release', until it has been built and tested
- [ ] Publish the pre-release to GitHub using "Publish Release"
2021-02-23 14:56:06 -08:00
2022-10-05 05:46:10 -07:00
## Binary Testing
2021-02-09 16:56:58 -08:00
2022-09-27 14:53:00 -07:00
- [ ] 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.)
2022-10-05 05:46:10 -07:00
- [ ] [Publish the release to GitHub ](https://github.com/ZcashFoundation/zebra/releases ) by disabling 'pre-release', then clicking "Publish Release"
2022-09-27 14:53:00 -07:00
- [ ] Wait until [the Docker images have been published ](https://github.com/ZcashFoundation/zebra/actions/workflows/release-binaries.yml )
2022-11-02 17:28:46 -07:00
- [ ] Test the Docker image using `docker run --tty --interactive zfnd/zebra:1.0.0-rc.<version>` <!-- TODO: replace with `zfnd/zebra` when we release 1.0.0 -->
2022-07-07 13:31:19 -07:00
- [ ] Turn off [Merge Freeze ](https://www.mergefreeze.com/installations/3676/branches ) for the whole repository
2021-02-09 16:56:58 -08:00
2022-10-11 18:17:55 -07:00
## Blog Post
If the release contains new features (`major` or `minor` ), or high-priority bug fixes:
- [ ] Ask the team about doing a blog post
2022-10-05 05:46:10 -07:00
If building or running fails after tagging:
1. Fix the bug that caused the failure
2022-07-07 13:31:19 -07:00
2. Increment versions again, following these instructions from the start
2022-10-05 05:46:10 -07:00
3. Update the code and documentation with a **new** git tag
2022-07-07 13:31:19 -07:00
4. Update `CHANGELOG.md` with details about the fix
5. Tag a **new** release