zebra/.github/PULL_REQUEST_TEMPLATE/release-checklist.md

---
name: Release Checklist Template
about: Checklist of versioning to create a taggable commit for Zebra
title: ''
labels:
assignees: ''

---

## Versioning

### Which Crates to Increment

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.

- [ ] Increment the crates that have new commits since the last version update
- [ ] Increment any crates that depend on crates that have changed
- [ ] Use the `zebrad` crate version in the `zebra-network` user agent string
      (currently the constant `USER_AGENT` in `zebra-network/src/constants.rs`)
- [ ] Use the latest git tag in `README.md`

### How to Increment Versions

Zebra follows [semantic versioning](https://semver.org).

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.

Optionally, if a `MINOR` feature pre-release breaks `MAJOR` API compatibility:

2. Increment the `MAJOR` version, and reset all the other versions to zero

#### 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

### 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`
- [ ] `Cargo.lock`: automatically generated by `cargo build`

Merge all these version increments as one commit, by squashing and rebasing the PR onto the main branch.

After you have your changes pushed start a PR with them using this template by adding `&template=release-checklist.md` to the comparing url ([Example](https://github.com/ZcashFoundation/zebra/compare/v1.0.0-alpha.16?expand=1&template=release-checklist.md)).

#### Version Tooling

You can use `fastmod` to interactively find and replace versions.

For example, for `zebra-1.0.0-alpha.12`, we did:
```
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.12' '1.0.0-alpha.13'
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.11' '1.0.0-alpha.12'
fastmod --extensions rs,toml,md --fixed-strings '1.0.0-alpha.10' '1.0.0-alpha.11'
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
```

### Reviewing Version Bump Pull Requests

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.

## Initial Testing

- [ ] After any changes, test that the `cargo install` command in works. Use
      e.g. `cargo install --locked --path zebrad`.
      
## 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:

- [ ] The "Beta Release" section
- [ ] The "Known Issues" section 

to ensure that any items that are resolved in the latest release are no longer listed in the README. 

## 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](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:
- [ ] Copy the draft changelog into `CHANGELOG.md`
- [ ] Delete any trivial changes
- [ ] 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
- [ ] Create a draft PR to update `CHANGELOG.md`

#### 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.

## After merging the version update PR
- [ ] Check for any PRs that have been merged since you created the draft PR to update `CHANGELOG.md` and push any updates if necessary
- [ ] Mark the PR to update `CHANGELOG.md` as "Ready for Review"
- [ ] Once the changelog PR has been approved and merged, update the draft release with the final changelog
- [ ] Set the release title to `Zebra ` followed by the version tag, for example: `Zebra 1.0.0-alpha.0` 
- [ ] Set the tag name to the version tag, for example: `1.0.0-alpha.0`
- [ ] Set the release to target the `main` branch
- [ ] Mark the release as 'pre-release' (until we are no longer alpha/beta)

## Final Testing

- [ ] After tagging the release, test that the exact `cargo install` command in
      `README.md` works (`--git` behaves a bit differently to `--path`)

If the build fails after tagging:
1. fix the build
2. check if the fixes changed any extra crates, and do the required version increments
3. update `README.md` with a **new** git tag
4. update `CHANGELOG.md` with details about the fix
5. tag a **new** release