change(doc): Update README and release checklist for the release cand…

…idate (#5314) * Add a Docker run command to the README * Update the README with some user-relevant release candidate goals * Update the release template for the release candidate * Fix beta crate explanation * Be more specific about what "this PR" means * Update docker command for latest tag changes * Update README Docker command based on tag changes * Make Zebra release versions more vague in README.md Co-authored-by: Pili Guerra <[email protected]> * Move build instructions to build section Co-authored-by: Pili Guerra <[email protected]> * Add newlines to separate heading and paragraphs * Remove extra newline * Add a note for a future command update * Remove manual build check, it doesn't have tier 1 support Co-authored-by: Pili Guerra <[email protected]>
ZcashFoundation · Oct 5, 2022 · fd63d33 · fd63d33
1 parent b366d6e
commit fd63d33
Show file tree

Hide file tree

Showing 2 changed files with 61 additions and 55 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md
@@ -12,46 +12,45 @@ assignees: ''
 ### How to Increment Versions
 
 Zebra follows [semantic versioning](https://semver.org).
+Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]
 
-Look for the [draft `zebrad` changelog](https://github.com/ZcashFoundation/zebra/releases) for the automatic version bump.
-This version is based on [the labels on the PRs in the release](https://github.com/ZcashFoundation/zebra/blob/main/.github/release-drafter.yml).
+The [draft `zebrad` changelog](https://github.com/ZcashFoundation/zebra/releases) will have an automatic version bump. This version is based on [the labels on the PRs in the release](https://github.com/ZcashFoundation/zebra/blob/main/.github/release-drafter.yml).
 
 Check that the automatic `zebrad` version increment is correct:
-1. If we're releasing a mainnet network upgrade, increment the `major` version of all Zebra crates
-2. If we're not releasing a mainnet network upgrade, check for features, major changes, deprecations, and removals. If this release has any, it is a `minor` release
-
-If we're not doing a `major` release, you need to check which crates have changed:
-1. Go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra
-2. Check if the last commit to each crate is a Zebra version bump. If it is a version bump, the crate has not changed since the last release.
-
-Once you know which crates have 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).
+If we're releasing a mainnet network upgrade, it is a `major` release:
+1. Increment the `major` version of _*all*_ the Zebra crates.
+2. Increment the `patch` version of the tower crates.
 
-Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE]
+If we're not releasing a mainnet network upgrade, check for features, major changes, deprecations, and removals. If this release has any, it is a `minor` release:
+1. Increment the `minor` version of `zebrad`.
+2. Increment the `pre-release` version of the other crates.
+3. Increment the `patch` version of the tower crates.
 
-### Reviewing Version Bumps
+Otherwise, it is a `patch` release:
+1. Increment the `patch` version of `zebrad`.
+2. Increment the `pre-release` version of the other crates.
+3. Increment the `patch` version of the tower crates.
 
-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.
+Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta `pre-release` version.
 
-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.
-
 ### 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
+
+zebrad (rc):
+- [ ] zebrad `Cargo.toml`
 - [ ] `zebra-network` protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rs
 - [ ] `README.md`
 - [ ] `book/src/user/install.md`
+
+crates (pre-release):
+- [ ] zebra-* `Cargo.toml`s
+
+tower (patch):
+- [ ] tower-* `Cargo.toml`s
+
+auto-generated:
 - [ ] `Cargo.lock`: run `cargo build` after updating all the `Cargo.toml`s
 
 #### Version Tooling
@@ -60,15 +59,16 @@ You can use `fastmod` to interactively find and replace versions.
 
 For example, you can do something like:
 ```
-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.26' '0.2.27' tower-batch tower-fallback
+fastmod --extensions rs,toml,md --fixed-strings '1.0.0-rc.0' '1.0.0-rc.1' zebrad README.md book/src/user/install.md zebra-network/src/constants.rs
+fastmod --extensions rs,toml,md --fixed-strings '1.0.0-beta.15' '1.0.0-beta.16' zebra-*
+fastmod --extensions rs,toml,md --fixed-strings '0.2.30' '0.2.31' tower-batch tower-fallback
 ```
 
 If you use `fastmod`, don't update versions in `CHANGELOG.md`.
 
 ## README
 
-We should update the README to:
+Update the README to:
 - [ ] Remove any "Known Issues" that have been fixed
 - [ ] 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`.
@@ -84,10 +84,10 @@ To do this you will need a synchronized `zcashd` node. You can request help from
 **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).
 
+We follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
 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
@@ -97,7 +97,7 @@ To create the final change log:
   - Prefer the "Fix" category if you're not sure
 
 <details>
-   
+
 #### Change Categories
 
 From "Keep a Changelog":
@@ -116,48 +116,44 @@ From "Keep a Changelog":
 
 After you have the version increments, the updated checkpoints and the updated changelog:
 
-- [ ] Make sure the PR with the new checkpoint hashes is already merged.
+- [ ] Make sure the PR with the new checkpoint hashes is already merged, or make it part of the changelog PR
 - [ ] Push the version increments and the updated changelog into a branch
-      (name suggestion, example: `v100-alpha0-release`)
+      (name suggestion, example: `v100-rc0-release`)
 - [ ] Create a release PR by adding `&template=release-checklist.md` to the
       comparing url ([Example](https://github.com/ZcashFoundation/zebra/compare/v100-alpha0-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).
 - [ ] Turn on [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches).
 - [ ] Once the PR is ready to be merged, unfreeze it [here](https://www.mergefreeze.com/installations/3676/branches).
       Do not unfreeze the whole repository.
 
 ### Create the Release
 
-- [ ] Once the PR has been merged,
-      create a new release using the draft release as a base,
+- [ ] Once the PR has been 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 tag name to the version tag,
-      for example: `v1.0.0-alpha.0`
+      for example: `v1.0.0-rc.0`
 - [ ] Set the release to target the `main` branch
 - [ ] Set the release title to `Zebra ` followed by the version tag,
-      for example: `Zebra 1.0.0-alpha.0`
+      for example: `Zebra 1.0.0-rc.0`
 - [ ] Replace the prepopulated draft changelog in the release description by the final
       changelog you created; starting just _after_ the title `## [Zebra ...` of
       the current version being released, and ending just _before_ the title of
       the previous release.
 - [ ] Mark the release as 'pre-release', until it has been built and tested
 - [ ] Publish the pre-release to GitHub using "Publish Release"
 
-## Build and Binary Testing
+## Binary Testing
 
-- [ ] After tagging the release, test that the exact `cargo install` command in `README.md` works
-      (`--git` behaves a bit differently to `--path`)
-- [ ] Test that the newly built Zebra starts correctly, by running `~/.cargo/bin/zebrad`
 - [ ] Wait until the [Docker binaries have been built on `main`](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-docker.yml), and the quick tests have passed.
       (You can ignore the full sync and `lightwalletd` tests, because they take about a day to run.)
-- [ ] Publish the release to GitHub by disabling 'pre-release', then clicking "Publish Release"
+- [ ] [Publish the release to GitHub](https://github.com/ZcashFoundation/zebra/releases) by disabling 'pre-release', then clicking "Publish Release"
 - [ ] Wait until [the Docker images have been published](https://github.com/ZcashFoundation/zebra/actions/workflows/release-binaries.yml)
+- [ ] Test the Docker image using `docker run zfnd/zebra:1.0.0-rc.<version>` <!-- TODO: replace with `docker run zfnd/zebra` when we release 1.0.0 -->
 - [ ] Turn off [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches) for the whole repository
 
-If the build fails after tagging:
-1. Fix the build
+If building or running fails after tagging:
+1. Fix the bug that caused the failure
 2. Increment versions again, following these instructions from the start
-3. Update `README.md` with a **new** git tag
+3. Update the code and documentation with a **new** git tag
 4. Update `CHANGELOG.md` with details about the fix
 5. Tag a **new** release
diff --git a/README.md b/README.md
@@ -55,28 +55,38 @@ Zebra aims to be
 [faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages)
 than other Zcash implementations.
 
-## Beta Releases
+## Release Candidates
 
-Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashFoundation/zebra/releases).
+Every few weeks, we release a [new Zebra version](https://github.com/ZcashFoundation/zebra/releases).
 
 Zebra's network stack is interoperable with `zcashd`,
 and Zebra implements all the features required to reach Zcash network consensus.
 
-Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade.
+Zebra also supports the [`lightwalletd` backend JSON-RPCs](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd).
 
+Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade.
 But it may not validate any:
 - Undocumented rules derived from Bitcoin
 - Undocumented network protocol requirements
 
 ## Getting Started
 
-Building `zebrad` requires [Rust](https://www.rust-lang.org/tools/install),
-[libclang](https://clang.llvm.org/get_started.html), and a C++ compiler.
+You can run Zebra using our Docker image.
+This command will run our latest release, and sync it to the tip:
+
+<!-- TODO: replace with `docker run zfnd/zebra` when we release 1.0.0 -->
+
+```sh
+docker run zfnd/zebra:1.0.0-rc.0
+```
+
+You can also [enable Zebra's RPC port](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd) and [configure other features](https://zebra.zfnd.org/user/run.html).
+
+### Build Instructions
 
-### Build and Run Instructions
+If you want to build `zebrad` yourself, you'll need [Rust](https://www.rust-lang.org/tools/install), [libclang](https://clang.llvm.org/get_started.html), a C++ compiler, and some other dependencies.
 
-`zebrad` is still under development, so there is no supported packaging or
-install mechanism. To run `zebrad`, follow the instructions to compile `zebrad`
+To run `zebrad`, follow the instructions to compile `zebrad`
 for your platform:
 
 1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).