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
### Which Crates to Increment
2021-08-26 15:45:19 -07:00
To check if any of the top-level crates need version increments, go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra and use the last modified dates of each crate. Alternatively you can use the github compare tool and check the `main` branch against the last tag ([Example](https://github.com/ZcashFoundation/zebra/compare/v1.0.0-alpha.15...main)). `git diff --stat <previous-release-tag> origin/main` is also useful to see what's changed.
2021-02-09 16:56:58 -08:00
- [ ] Increment the crates that have new commits since the last version update
- [ ] Increment any crates that depend on crates that have changed
2022-02-23 10:18:30 -08:00
- [ ] Keep a list of the crates that haven't been incremented, to include in the PR
2021-02-09 16:56:58 -08:00
### How to Increment Versions
Zebra follows [semantic versioning ](https://semver.org ).
2021-03-16 17:24:16 -07:00
Semantic versions look like: `MAJOR` .`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]`
2021-02-09 16:56:58 -08:00
#### Pre-Release Crates
2021-03-16 17:24:16 -07:00
Pre-Release versions have a `TAG` like "alpha" or "beta". For example: `1.0.0-alpha.0`
2021-02-09 16:56:58 -08:00
1. Increment the `PRE-RELEASE` version for the crate.
#### Unstable Crates
2021-03-16 17:24:16 -07:00
Unstable versions have a `MAJOR` version of zero. For example: `0.1.0`
2021-02-09 16:56:58 -08:00
1. Follow stable crate versioning, but increment the `MINOR` version for breaking changes
#### Stable Crates
2021-03-16 17:24:16 -07:00
For example: `1.0.0`
2021-02-09 16:56:58 -08:00
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
2021-03-16 17:24:16 -07:00
* check for types from dependencies that appear in the public API
2021-02-09 16:56:58 -08:00
2. MINOR versions for new features
3. PATCH versions for bug fixes
2021-03-16 17:24:16 -07:00
* includes dependency updates that don't impact the public API
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:
- [ ] zebra* `Cargo.toml` s
- [ ] tower-* `Cargo.toml` s
- [ ] `zebra-network` protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rs
- [ ] `README.md`
2021-12-23 05:16:15 -08:00
- [ ] `book/src/user/install.md`
2021-03-16 17:24:16 -07:00
- [ ] `Cargo.lock` : automatically generated by `cargo build`
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
```
2021-07-01 00:59:32 -07:00
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.12' '1.0.0-alpha.13'
fastmod --extensions rs,toml,md --fixed-strings '0.2.9' '0.2.10' tower-batch
fastmod --extensions rs,toml,md --fixed-strings '0.2.8' '0.2.9' tower-fallback
2021-02-22 23:31:02 -08:00
```
2021-12-23 05:16:15 -08:00
### Reviewing Version Bumps
2021-05-12 01:42:48 -07:00
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.
2021-11-02 08:36:47 -07:00
## README
As we resolve various outstanding known issues and implement new functionality with each release, we should double check the README for any necessary updates.
We should check and update if necessary:
2021-12-02 12:54:14 -08:00
- [ ] The "Known Issues" section
2021-11-02 08:36:47 -07:00
2021-12-02 12:54:14 -08:00
to ensure that any items that are resolved in the latest release are no longer listed in the README.
2021-03-22 21:39:12 -07:00
2021-02-09 16:56:58 -08:00
## Change Log
2021-06-22 06:31:30 -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 follow the [Keep a Changelog ](https://keepachangelog.com/en/1.0.0/ ) format.
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 ).
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
- 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.
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
After you have the version increments and the updated changelog:
2021-12-23 05:16:15 -08:00
- [ ] 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](https://github.com/ZcashFoundation/zebra/compare/v1.0.0-alpha.0-release?expand=1& template=release-checklist.md)).
2022-02-23 10:18:30 -08:00
- [ ] 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).
2022-04-05 11:06:46 -07:00
- [ ] While the PR is being reviewed, turn on [Merge Freeze ](https://www.mergefreeze.com/installations/3676/branches ) to stop other PRs merging
### Create the Release
2021-12-23 05:16:15 -08:00
- [ ] Once the release PR has been approved and 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 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 ...` )
2021-12-02 12:54:14 -08:00
- [ ] Set the tag name to the version tag, for example: `v1.0.0-alpha.0`
2021-03-16 17:24:16 -07:00
- [ ] Set the release to target the `main` branch
2021-02-23 14:56:06 -08:00
- [ ] Mark the release as 'pre-release' (until we are no longer alpha/beta)
2021-12-23 05:16:15 -08:00
- [ ] Publish the release
2021-02-23 14:56:06 -08:00
2021-02-09 16:56:58 -08:00
## Final Testing
2021-10-20 11:02:07 -07:00
- [ ] After tagging the release, test that the exact `cargo install` command in
`README.md` works (`--git` behaves a bit differently to `--path` )
2022-04-05 11:06:46 -07:00
- [ ] Turn off [Merge Freeze ](https://www.mergefreeze.com/installations/3676/branches ) to start merging PRs again
2021-02-09 16:56:58 -08:00
If the build fails after tagging:
1. fix the build
2022-04-05 11:06:46 -07:00
2. increment versions again, following these instructions from the start
2021-02-09 16:56:58 -08:00
3. update `README.md` with a **new** git tag
2021-06-22 06:31:30 -07:00
4. update `CHANGELOG.md` with details about the fix
2021-08-26 15:45:19 -07:00
5. tag a **new** release