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

156 lines
6.4 KiB
Markdown
Raw Normal View History

---
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
- [ ] Keep a list of the crates that haven't been incremented, to include in the PR
### 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.
#### 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`
- [ ] `book/src/user/install.md`
- [ ] `Cargo.lock`: automatically generated by `cargo build`
#### Version Tooling
You can use `fastmod` to interactively find and replace versions.
Use `MockedClientHandle` in other tests (#3241) * Move `MockedClientHandle` to `peer` module It's more closely related to a `Client` than the `PeerSet`, and this prepares it to be used by other tests. * Rename `MockedClientHandle` to `ClientTestHarness` Reduce confusion, and clarify that the client is not mocked. Co-authored-by: teor <teor@riseup.net> * Add clarification to `mock_peers` documentation Explicitly say how the generated data is returned. * Rename method to `wants_connection_heartbeats` The `Client` service only represents one direction of a connection, so `is_connected` is not the exact term. Co-authored-by: teor <teor@riseup.net> * Mock `Client` instead of `LoadTrackedClient` Move where the conversion from mocked `Client` to mocked `LoadTrackedClient` in order to make the test helper more easily used by other tests. * Use `ClientTestHarness` in `initialize` tests Replace the boilerplate code to create a fake `Client` instance with usages of the `ClientTestHarness` constructor. * Allow receiving requests from `Client` instance Create a helper type to wrap the result, to make it easier to assert on specific events after trying to receive a request. * Allow inspecting the current error in the slot Share the `ErrorSlot` between the `Client` and the handle, so that the handle can be used to inspect the contents of the `ErrorSlot`. * Allow placing an error into the `ErrorSlot` Assuming it is initially empty. If it already has an error, the code will panic. * Allow gracefully closing the request receiver Close the endpoint with the appropriate call to the `close()` method. * Allow dropping the request receiver endpoint Forcefully closes the endpoint. * Rename field to `client_request_receiver` Also rename the related methods to include `outbound_client_request_receiver` to make it more precise. Co-authored-by: teor <teor@riseup.net> * Allow dropping the heartbeat shutdown receiver Allows the `Client` to detect that the channel has been closed. * Rename fn. to `drop_heartbeat_shutdown_receiver` Make it clear that it affects the heartbeat task. Co-authored-by: teor <teor@riseup.net> * Move `NowOrLater` into a new `now-or-later` crate Make it easily accessible to other crates. * Add `IsReady` extension trait for `Service` Simplifies checking if a service is immediately ready to be called. * Add extension method to check for readiness error Checks if the `Service` isn't immediately ready because a call to `ready` immediately returns an error. * Rename method to `is_failed` Avoid negated method names. Co-authored-by: teor <teor@riseup.net> * Add a `IsReady::is_pending` extension method Checks if a `Service` is not ready to be called. * Use `ClientTestHarness` in `Client` test vectors Reduce repeated code and try to improve readability. * Create a new `ClientTestHarnessBuilder` type A builder to create test `Client` instances using mock data which can be tracked and manipulated through a `ClientTestHarness`. * Allow configuring the `Client`'s mocked version Add a `with_version` builder method. * Use `ClientTestHarnessBuilder` in `PeerVersions` Use the builder to set the peer version, so that the `version` parameter can be removed from the constructor later. * Use a default mock version where possible Reduce noise when setting up the harness for tests that don't really care about the remote peer version. * Remove `Version` parameter from the `build` method The `with_version` builder method should be used instead. * Fix some typos and outdated info in the release checklist * Add extra client tests for zero and multiple readiness checks (#3273) And document existing tests. * Replace `NowOrLater` with `futures::poll!` (#3272) * Replace NowOrLater with the futures::poll! macro in zebrad * Replace NowOrLater with the futures::poll! macro in zebra-test * Remove the now-or-later crate * remove unused imports * rustfmt Co-authored-by: teor <teor@riseup.net> Co-authored-by: Alfredo Garcia <oxarbitrage@gmail.com>
2021-12-21 12:13:26 -08:00
For example, you can do something like:
```
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
```
### Reviewing Version Bumps
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.
## 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 "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. Keep the list of those, to include in the PR
- [ ] 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.
## Create the Release
### Create the Release PR
After you have the version increments and the updated changelog:
- [ ] 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)).
- [ ] 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).
- [ ] 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
- [ ] 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 ...`)
- [ ] Set the tag name to the version tag, for example: `v1.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)
- [ ] Publish the release
## Final Testing
- [ ] After tagging the release, test that the exact `cargo install` command in
`README.md` works (`--git` behaves a bit differently to `--path`)
- [ ] Turn off [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches) to start merging PRs again
If the build fails after tagging:
1. fix the build
2. increment versions again, following these instructions from the start
3. update `README.md` with a **new** git tag
4. update `CHANGELOG.md` with details about the fix
5. tag a **new** release