From 112d16d2c74238bc06031f2ad8eb4be07bf6b03d Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 3 Oct 2022 12:39:52 +1000 Subject: [PATCH 01/13] Add a Docker run command to the README --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b5ee6843f78..fdf74f23de7 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,20 @@ But it may not validate any: ## 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: +```sh +docker run zfnd/zebra +``` + +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). + +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. -### Build and Run Instructions +### Build Instructions -`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). From 0272d9f4a4e048d7356c9b5819224d70b2640da0 Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 3 Oct 2022 12:42:48 +1000 Subject: [PATCH 02/13] Update the README with some user-relevant release candidate goals --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fdf74f23de7..8cb38d6fb9c 100644 --- a/README.md +++ b/README.md @@ -55,15 +55,16 @@ 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 [release candidate](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 From f388f8dd67cfe533fcb6b7df5704e84889e8ec5f Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 3 Oct 2022 13:02:43 +1000 Subject: [PATCH 03/13] Update the release template for the release candidate --- .../release-checklist.md | 85 +++++++++---------- 1 file changed, 42 insertions(+), 43 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index 4ca3906da99..c9b360bc0db 100644 --- 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//` -Where `` 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` 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 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
- + #### Change Categories From "Keep a Changelog": @@ -116,27 +116,25 @@ 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 this 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 @@ -151,13 +149,14 @@ After you have the version increments, the updated checkpoints and the updated c - [ ] 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` - [ ] 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 From ed8bcd1f71c9a19cba930e747e6121ec9d7036bf Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 3 Oct 2022 13:08:59 +1000 Subject: [PATCH 04/13] Fix beta crate explanation --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index c9b360bc0db..cfa77a8fb2f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -32,7 +32,7 @@ Otherwise, it is a `patch` release: 2. Increment the `pre-release` version of the other crates. 3. Increment the `patch` version of the tower crates. -Zebra's Rust API is not stable or supported, so we keep all the crates on the same `beta` release version. +Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta `pre-release` version. ### Version Locations From 46d1eaf288e5ddf1ec06c29dba0d9ebcc3dbe7f9 Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 3 Oct 2022 13:12:17 +1000 Subject: [PATCH 05/13] Be more specific about what "this PR" means --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index cfa77a8fb2f..cf8ae617ecf 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -116,7 +116,7 @@ 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, or make it part of this PR +- [ ] 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-rc0-release`) - [ ] Create a release PR by adding `&template=release-checklist.md` to the From 19c67d6dda1c1fb85f43d4f10323becb778ef612 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:04:51 +1000 Subject: [PATCH 06/13] Update docker command for latest tag changes --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index cf8ae617ecf..623dc009a1d 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -151,7 +151,7 @@ After you have the version increments, the updated checkpoints and the updated c (You can ignore the full sync and `lightwalletd` tests, because they take about a day to run.) - [ ] [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` +- [ ] Test the Docker image using `docker run zfnd/zebra:1.0.0-rc.` - [ ] Turn off [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches) for the whole repository If building or running fails after tagging: From 22d629a19faaa2ce1a35222de23d4b0723aa64b5 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:07:26 +1000 Subject: [PATCH 07/13] Update README Docker command based on tag changes --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8cb38d6fb9c..64d798dc405 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,11 @@ But it may not validate any: You can run Zebra using our Docker image. This command will run our latest release, and sync it to the tip: + + + ```sh -docker run zfnd/zebra +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). From 9a2ede1740d6d8c4e2776a7b3e941fa1f80df25a Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:08:09 +1000 Subject: [PATCH 08/13] Make Zebra release versions more vague in README.md Co-authored-by: Pili Guerra --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 64d798dc405..9ce69efe1a7 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ than other Zcash implementations. ## Release Candidates -Every few weeks, we release a new Zebra [release candidate](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. From 87e9443653827f839e9c19522d1da5a2d046699d Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:08:42 +1000 Subject: [PATCH 09/13] Move build instructions to build section Co-authored-by: Pili Guerra --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 9ce69efe1a7..a0bbe9ea5fb 100644 --- a/README.md +++ b/README.md @@ -82,11 +82,9 @@ 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). -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. ### Build 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. To run `zebrad`, follow the instructions to compile `zebrad` for your platform: From ed4d32ff02aa60cb41a8787b089d606d9417f230 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:18:41 +1000 Subject: [PATCH 10/13] Add newlines to separate heading and paragraphs --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index a0bbe9ea5fb..8171f58a141 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,9 @@ You can also [enable Zebra's RPC port](https://github.com/ZcashFoundation/zebra# ### Build 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. + To run `zebrad`, follow the instructions to compile `zebrad` for your platform: From efa0ee58da237197b28ee2b627ef75bb426724c7 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:19:03 +1000 Subject: [PATCH 11/13] Remove extra newline --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 8171f58a141..52fea7f2379 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,6 @@ 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 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. From 3a36a1d7a87d025d8bd596fceefa223693e58787 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 4 Oct 2022 06:19:44 +1000 Subject: [PATCH 12/13] Add a note for a future command update --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index 623dc009a1d..db8c1dc9bcb 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -151,7 +151,7 @@ After you have the version increments, the updated checkpoints and the updated c (You can ignore the full sync and `lightwalletd` tests, because they take about a day to run.) - [ ] [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.` +- [ ] Test the Docker image using `docker run zfnd/zebra:1.0.0-rc.` - [ ] Turn off [Merge Freeze](https://www.mergefreeze.com/installations/3676/branches) for the whole repository If building or running fails after tagging: From fc8e60158a497cd7b73f8236a8b4c3e032116031 Mon Sep 17 00:00:00 2001 From: teor Date: Wed, 5 Oct 2022 17:36:57 +1000 Subject: [PATCH 13/13] Remove manual build check, it doesn't have tier 1 support --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index db8c1dc9bcb..135906a6967 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -142,11 +142,8 @@ After you have the version increments, the updated checkpoints and the updated c - [ ] 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](https://github.com/ZcashFoundation/zebra/releases) by disabling 'pre-release', then clicking "Publish Release"