--- 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 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//` Where `` 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`. ## 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