zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Make the release checklist shorter and hide some details (#4712) 

* Make the release checklist shorter and hide some details

* Ignore any `fastmod` updates to previous release notes in `CHANGELOG.md`

* Use recent versions in examples

* Fix markdown that doesn't render correctly

* Fix some weird line breaks

* Use capital letters to start list items

* Clarify `fastmod` and `CHANGELOG.md`

* Clarify version format by changing highlighting
This commit is contained in:
teor 2022-07-08 06:31:19 +10:00 committed by GitHub
parent c27166013d
commit a55262c3ac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 59 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
.github/PULL_REQUEST_TEMPLATE/release-checklist.md vendored
View File

@ -11,8 +11,19 @@ assignees: ''
### Which Crates to Increment ### 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. To check if any of the top-level crates need version increments:
1. Go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra
2. Check if the last commit was a Zebra version bump, or something else
<details>
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))
- Use `git diff --stat <previous-release-tag> origin/main`
</details>
Once you know which crates have changed:
- [ ] Increment the crates that have new commits since the last version update - [ ] Increment the crates that have new commits since the last version update
- [ ] Increment any crates that depend on crates that have changed - [ ] 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 - [ ] Keep a list of the crates that haven't been incremented, to include in the PR
@ -21,7 +32,9 @@ To check if any of the top-level crates need version increments, go to the zebra
Zebra follows [semantic versioning](https://semver.org). Zebra follows [semantic versioning](https://semver.org).
Semantic versions look like: `MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]` Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]
<details>
#### Pre-Release Crates #### Pre-Release Crates
@ -46,6 +59,17 @@ Increment the first version component in this list, and reset the other componen
3. PATCH versions for bug fixes 3. PATCH versions for bug fixes
* includes dependency updates that don't impact the public API * includes dependency updates that don't impact the public API
### 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.
</details>
### Version Locations ### Version Locations
Once you know which versions you want to increment, you can find them in the: Once you know which versions you want to increment, you can find them in the:
@ -62,35 +86,23 @@ You can use `fastmod` to interactively find and replace versions.
For example, you can do something like: 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 '1.0.0-beta.11' '1.0.0-beta.12'
fastmod --extensions rs,toml,md --fixed-strings '0.2.9' '0.2.10' tower-batch fastmod --extensions rs,toml,md --fixed-strings '0.2.26' '0.2.27' tower-batch tower-fallback
fastmod --extensions rs,toml,md --fixed-strings '0.2.8' '0.2.9' tower-fallback
``` ```
### Reviewing Version Bumps If you use `fastmod`, don't update versions in `CHANGELOG.md`.
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 ## 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 update the README to:
- [ ] Remove any "Known Issues" that have been fixed
We should check and update if necessary: - [ ] 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`.
- [ ] The "Known Issues" section to ensure that any items that are resolved in the latest release are no longer listed in the README.
- [ ] The "Build and Run Instructions" section. Check if any new dependencies were introduced and
list them if needed; one possible approach is to check for changes in the `Dockerfile`
since the last tag: `git diff <previous-release-tag> docker/Dockerfile`.
## Change Log ## 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`. **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 follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
@ -102,8 +114,10 @@ To create the final change log:
- [ ] Combine duplicate changes - [ ] Combine duplicate changes
- [ ] Edit change descriptions so they are consistent, and make sense to non-developers - [ ] Edit change descriptions so they are consistent, and make sense to non-developers
- [ ] Check the category for each change - [ ] Check the category for each change
- prefer the "Fix" category if you're not sure - Prefer the "Fix" category if you're not sure
<details>
#### Change Categories #### Change Categories
From "Keep a Changelog": From "Keep a Changelog":
@ -114,6 +128,8 @@ From "Keep a Changelog":
* `Fixed` for any bug fixes. * `Fixed` for any bug fixes.
* `Security` in case of vulnerabilities. * `Security` in case of vulnerabilities.
</details>
## Create the Release ## Create the Release
### Create the Release PR ### Create the Release PR
@ -124,22 +140,22 @@ After you have the version increments and the updated changelog:
(name suggestion, example: `v1.0.0-alpha.0-release`) (name suggestion, example: `v1.0.0-alpha.0-release`)
- [ ] Create a release PR by adding `&template=release-checklist.md` to the - [ ] 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)). 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. - [ ] 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). - [ ] Also add the list of not-bumped crates as a comment (can use the same comment as the previous one).
- [ ] Turn on [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches). - [ ] Turn on [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches).
- [ ] Once the PR is ready to be merged, unfreeze it - [ ] Once the PR is ready to be merged, unfreeze it [here](https://www.mergefreeze.com/installations/3676/branches).
[here](https://www.mergefreeze.com/installations/3676/branches). Do not Do not unfreeze the whole repository.
unfreeze the whole repository.
### Create the Release ### Create the Release
- [ ] Once the PR has been merged, create a new release using the draft release - [ ] Once the PR has been merged,
as a base, by clicking the Edit icon in the [draft create a new release using the draft release as a base,
release](https://github.com/ZcashFoundation/zebra/releases). by clicking the Edit icon in the [draft release](https://github.com/ZcashFoundation/zebra/releases)
- [ ] Set the tag name to the version tag, for example: `v1.0.0-alpha.0` - [ ] Set the tag name to the version tag,
for example: `v1.0.0-alpha.0`
- [ ] Set the release to target the `main` branch - [ ] Set the release to target the `main` branch
- [ ] Set the release title to `Zebra ` followed by the version tag, for example: - [ ] Set the release title to `Zebra ` followed by the version tag,
`Zebra 1.0.0-alpha.0` for example: `Zebra 1.0.0-alpha.0`
- [ ] Copy the final changelog of this release to the release description - [ ] Copy the final changelog of this release to the release description
(starting just _after_ the title `## [Zebra ...`) (starting just _after_ the title `## [Zebra ...`)
- [ ] Mark the release as 'pre-release' (until we are no longer alpha/beta) - [ ] Mark the release as 'pre-release' (until we are no longer alpha/beta)
@ -147,15 +163,13 @@ After you have the version increments and the updated changelog:
## Final Testing ## Final Testing
- [ ] After tagging the release, test that the exact `cargo install` command in - [ ] After tagging the release, test that the exact `cargo install` command in `README.md` works
`README.md` works (`--git` behaves a bit differently to `--path`) (`--git` behaves a bit differently to `--path`)
- [ ] Turn off [Merge - [ ] Turn off [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches) for the whole repository
Freeze](https://www.mergefreeze.com/installations/3676/branches) for the
whole repository.
If the build fails after tagging: If the build fails after tagging:
1. fix the build 1. Fix the build
2. increment versions again, following these instructions from the start 2. Increment versions again, following these instructions from the start
3. update `README.md` with a **new** git tag 3. Update `README.md` with a **new** git tag
4. update `CHANGELOG.md` with details about the fix 4. Update `CHANGELOG.md` with details about the fix
5. tag a **new** release 5. Tag a **new** release