Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change(doc): Update README and release checklist for the release candidate #5314

Merged
merged 13 commits into from
Oct 5, 2022
Merged

change(doc): Update README and release checklist for the release candidate #5314

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
112d16d
Add a Docker run command to the README
teor2345 Oct 3, 2022
0272d9f
Update the README with some user-relevant release candidate goals
teor2345 Oct 3, 2022
f388f8d
Update the release template for the release candidate
teor2345 Oct 3, 2022
ed8bcd1
Fix beta crate explanation
teor2345 Oct 3, 2022
46d1eaf
Be more specific about what "this PR" means
teor2345 Oct 3, 2022
19c67d6
Update docker command for latest tag changes
teor2345 Oct 3, 2022
22d629a
Update README Docker command based on tag changes
teor2345 Oct 3, 2022
9a2ede1
Make Zebra release versions more vague in README.md
teor2345 Oct 3, 2022
87e9443
Move build instructions to build section
teor2345 Oct 3, 2022
ed4d32f
Add newlines to separate heading and paragraphs
teor2345 Oct 3, 2022
efa0ee5
Remove extra newline
teor2345 Oct 3, 2022
3a36a1d
Add a note for a future command update
teor2345 Oct 3, 2022
fc8e601
Remove manual build check, it doesn't have tier 1 support
teor2345 Oct 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 42 additions & 43 deletions .github/PULL_REQUEST_TEMPLATE/release-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
mpguerra marked this conversation as resolved.
Show resolved Hide resolved

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.
mpguerra marked this conversation as resolved.
Show resolved Hide resolved

### 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
Expand All @@ -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
mpguerra marked this conversation as resolved.
Show resolved Hide resolved
```

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`.
Expand All @@ -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
Expand All @@ -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":
Expand All @@ -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 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
Expand All @@ -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`
teor2345 marked this conversation as resolved.
Show resolved Hide resolved
- [ ] 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
24 changes: 16 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,28 +55,36 @@ 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).
teor2345 marked this conversation as resolved.
Show resolved Hide resolved
teor2345 marked this conversation as resolved.
Show resolved Hide resolved

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).
mpguerra marked this conversation as resolved.
Show resolved Hide resolved

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:
```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).

teor2345 marked this conversation as resolved.
Show resolved Hide resolved
If you want to build `zebrad` yourself, you'll need [Rust](https://www.rust-lang.org/tools/install),
teor2345 marked this conversation as resolved.
Show resolved Hide resolved
teor2345 marked this conversation as resolved.
Show resolved Hide resolved
[libclang](https://clang.llvm.org/get_started.html), a C++ compiler, and some other dependencies.
teor2345 marked this conversation as resolved.
Show resolved Hide resolved

### Build and Run Instructions
### Build Instructions

teor2345 marked this conversation as resolved.
Show resolved Hide resolved
`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).
Expand Down