release(1.0.0-rc.2): updated versions and CHANGELOG.md

[dconnolly]

I haven't touched zebra-dependencies-for-audit.md.

Versioning

How to Increment Versions

Zebra follows semantic versioning.
Semantic versions look like: MAJOR.MINOR.PATCH[-TAG.PRE-RELEASE]

The draft zebrad changelog will have an automatic version bump. This version is based on the labels on the PRs in the release.

Check that the automatic [zebra](https://github.com/ZcashFoundation/zebra)d version increment is correct:

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.

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.

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.

Zebra's Rust API is not stable or supported, so we keep all the crates on the same beta pre-release version.

Version Locations

Once you know which versions you want to increment, you can find them in the:

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/docker.md

crates (pre-release):

• zebra-* Cargo.tomls

tower (patch):

• tower-* Cargo.tomls

auto-generated:

• Cargo.lock: run cargo build after updating all the Cargo.tomls

Version Tooling

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-rc.0' '1.0.0-rc.1' zebrad README.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

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.

Checkpoints

With every release and for performance reasons, we want to update the zebra checkpoints. More information on how to do this can be found in the zebra-checkpoints README.

To do this you will need a synchronized zcashd node. You can request help from other zebra team members to submit this PR if you can't make it yourself at the moment of the release.

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 use the Release Drafter workflow to automatically create a draft changelog.

We follow the Keep a Changelog 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
• 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, the updated checkpoints and the updated changelog:

• 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
  (for example: bump-v1.0.0-rc.0 - this needs to be different to the tag name)
• Create a release PR by adding &template=release-checklist.md to the
  comparing url (Example).
  • Add the list of deleted changelog entries as a comment to make reviewing easier.
• Turn on Merge Freeze.
• Once the PR is ready to be merged, unfreeze it here.
  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,
  by clicking the Edit icon in the draft release
• Set the tag name to the version tag,
  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-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"

Binary Testing

• Wait until the Docker binaries have been built on main, 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"
• Wait until the Docker images have been published
• Test the Docker image using docker run --tty --interactive zfnd/zebra:1.0.0-rc.<version>
• Turn off Merge Freeze for the whole repository

Blog Post

If the release contains new features (major or minor), or high-priority bug fixes:

• Ask the team about doing a blog post

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 the code and documentation with a new git tag
4. Update CHANGELOG.md with details about the fix
5. Tag a new release

[dconnolly]

Deleted changelog entries:

change(rpc): Refactor RPCs using a state tip height function (#5540)
build(deps): bump hyper from 0.14.21 to 0.14.22 (#5525)
build(deps): bump num_cpus from 1.13.1 to 1.14.0 (#5566)
build(deps): bump prost from 0.11.0 to 0.11.2 (#5564)
build(deps): bump reviewdog/action-actionlint from 1.33.1 to 1.34.0 (#5534)
build(deps): bump tj-actions/changed-files from 34.0.2 to 34.0.3 (#5535)
build(deps): bump tj-actions/changed-files from 34.0.3 to 34.3.1 (#5563)
change(rpc): add submitblock RPC method (#5526)
cleanup(deps): Remove unused fpe dependency and cleanup references (#5541)
fix(README): Clarify alternate dependency names (#5528)
fix(build): Disable new Rust 1.65 lints and fix some test errors (#5549)
fix(ci): Add a missing runs-on field to a patch workflow (#5562)
fix(ci): Make "test all" log output shorter (#5521)
fix(ci): Run required jobs on dependent PRs (#5550)
fix(ci): Stop using multiple jobs for quick Google Cloud tests (#5560)
fix(doc): Use a more reliable release template branch name and docker command (#5519)

[teor2345]

Thanks, this looks good!

I checked the draft release notes, and these user-visible changes seem to be missing?

- change(rpc): Select getblocktemplate RPC transactions according to ZIP-317 ([#5724](https://github.com/ZcashFoundation/zebra/pull/5724))
- change(state): Check block and transaction Sprout anchors in parallel ([#5742](https://github.com/ZcashFoundation/zebra/pull/5742))
- fix(consensus): Check network and P2SH addresses for mining config and funding streams ([#5620](https://github.com/ZcashFoundation/zebra/pull/5620))
- change(rpc): return an error from getblocktemplate method if Zebra is not synced to network tip ([#5623](https://github.com/ZcashFoundation/zebra/pull/5623))
- feat(rpc): populate some getblocktemplate RPC block header fields using the state best chain tip  ([#5659](https://github.com/ZcashFoundation/zebra/pull/5659))
- change(consensus) verify that mempool transaction UTXOs are in the best chain ([#5616](https://github.com/ZcashFoundation/zebra/pull/5616))
- change(consensus): Update mainnet and testnet checkpoints on 2022-12-01 ([#5754](https://github.com/ZcashFoundation/zebra/pull/5754))
- change(log): Log loaded config path when Zebra starts up ([#5733](https://github.com/ZcashFoundation/zebra/pull/5733))
- change(mempool): Contextually validates mempool transactions in best chain ([#5716](https://github.com/ZcashFoundation/zebra/pull/5716))
- change(rpc): generate coinbase transactions in the getblocktemplate RPC ([#5580](https://github.com/ZcashFoundation/zebra/pull/5580))
- fix(doc): Clarify inbound and outbound port requirements ([#5584](https://github.com/ZcashFoundation/zebra/pull/5584))

And the "fix RPC bugs" part of this change:

- change(ci): add acceptance test for getblocktemplate RPC in CI, and fix RPC bugs ([#5761](https://github.com/ZcashFoundation/zebra/pull/5761))

This would be user-visible, but it doesn't actually work yet, so I guess we should leave it out:

- ci(docs): update our Docker Hub documentation with our README ([#5779](https://github.com/ZcashFoundation/zebra/pull/5779))

[teor2345]

I haven't touched zebra-dependencies-for-audit.md.

I don't think it needs an update yet.

We've done these refactors in consensus-critical code:

• fix(consensus): Check network and P2SH addresses for mining config and funding streams
• change(state): Check block and transaction Sprout anchors in parallel

These changes to important but not consensus-critical code:

• fix(sync): Make the syncer ignore some new block verification errors
• fix(sync): Pause new downloads when Zebra reaches the lookahead limit
• change(mempool): verify that mempool transaction UTXOs are in the best chain
• change(mempool): Evict transactions from the mempool using the ZIP-317 conventional fee
• change(mempool): Contextually validates mempool transactions in best chain

And these security fixes:

• fix(rpc): Shut down the RPC server properly when Zebra shuts down

We've also made these changes to out of scope dependencies:

• build(deps): bump zcash_proofs from 0.8.0 to 0.9.0 and zcash_primitives from 0.8.1 to 0.9.0
  • this doesn't change the downloads code (which is in scope)

[codecov]

Codecov Report

Merging #5784 (3627fd9) into main (d8834c0) will decrease coverage by 0.07%.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5784      +/-   ##
==========================================
- Coverage   78.77%   78.69%   -0.08%     
==========================================
  Files         307      307              
  Lines       38730    38730              
==========================================
- Hits        30508    30479      -29     
- Misses       8222     8251      +29     

[arya2]

Thank you!

Version bumps look good.

A couple other user-visible changes in the commits since rc.1 that seem to be missing:

- rpc(config): Add a `mining` section with miner address to config ([#5491](https://github.com/ZcashFoundation/zebra/pull/5508))
- fix(zebrad) print usage info for --help flag ([#5634](https://github.com/ZcashFoundation/zebra/pull/5634))

[dconnolly]

Thanks, this looks good!

I checked the draft release notes, and these user-visible changes seem to be missing?

- change(rpc): Select getblocktemplate RPC transactions according to ZIP-317 ([#5724](https://github.com/ZcashFoundation/zebra/pull/5724))
- change(state): Check block and transaction Sprout anchors in parallel ([#5742](https://github.com/ZcashFoundation/zebra/pull/5742))
- fix(consensus): Check network and P2SH addresses for mining config and funding streams ([#5620](https://github.com/ZcashFoundation/zebra/pull/5620))
- change(rpc): return an error from getblocktemplate method if Zebra is not synced to network tip ([#5623](https://github.com/ZcashFoundation/zebra/pull/5623))
- feat(rpc): populate some getblocktemplate RPC block header fields using the state best chain tip  ([#5659](https://github.com/ZcashFoundation/zebra/pull/5659))
- change(consensus) verify that mempool transaction UTXOs are in the best chain ([#5616](https://github.com/ZcashFoundation/zebra/pull/5616))
- change(consensus): Update mainnet and testnet checkpoints on 2022-12-01 ([#5754](https://github.com/ZcashFoundation/zebra/pull/5754))
- change(log): Log loaded config path when Zebra starts up ([#5733](https://github.com/ZcashFoundation/zebra/pull/5733))
- change(mempool): Contextually validates mempool transactions in best chain ([#5716](https://github.com/ZcashFoundation/zebra/pull/5716))
- change(rpc): generate coinbase transactions in the getblocktemplate RPC ([#5580](https://github.com/ZcashFoundation/zebra/pull/5580))
- fix(doc): Clarify inbound and outbound port requirements ([#5584](https://github.com/ZcashFoundation/zebra/pull/5584))

And the "fix RPC bugs" part of this change:

- change(ci): add acceptance test for getblocktemplate RPC in CI, and fix RPC bugs ([#5761](https://github.com/ZcashFoundation/zebra/pull/5761))

This would be user-visible, but it doesn't actually work yet, so I guess we should leave it out:

- ci(docs): update our Docker Hub documentation with our README ([#5779](https://github.com/ZcashFoundation/zebra/pull/5779))

Aha, I think I was looking at this one instead

https://github.com/ZcashFoundation/zebra/releases/tag/untagged-5d4059e759081549929f

[teor2345]

We might have forgotten to delete the draft release after the last actual release, or release drafter made a duplicate?

We should add that to the checklist.

[dconnolly]

We might have forgotten to delete the draft release after the last actual release, or release drafter made a duplicate?

We should add that to the checklist.

Yeah the two draft releases were confusing to me

[teor2345]

We might have forgotten to delete the draft release after the last actual release, or release drafter made a duplicate?
We should add that to the checklist.

Yeah the two draft releases were confusing to me

I've fixed the release checklist in PR #5793, so we use the latest draft, and delete all drafts after the release

[dconnolly]

This PR has been unfrozen:

[teor2345]

It looks like you pushed 20 separate commits in an hour, and hit the API rate limit for Zebra (or for the Foundation). This caused this PR's jobs to fail. It can also make unrelated PRs fail.

Here's one of the detailed rate limit messages, from about 45 minutes ago:

reviewdog: post failed for codespell: fail to parse diff: GET https://api.github.com/repos/ZcashFoundation/zebra/pulls/5784: 403 API rate limit exceeded for installation ID 1523599. [rate reset in 35m43s]

It's ok to push lots of commits, they just need to be pushed in batches.

We might also have a lower rate limit since we switched to the free plan, we've hit it twice in a week. We might be able to work around that by combining some jobs. (For example, the individual crate build jobs, or the skipped jobs for the GCP workflows.)

[teor2345]

Thanks, looks good!

I've restarted all the rate-limited CI jobs.

[arya2]

@Mergifyio refresh

[mergify]

refresh

✅ Pull request refreshed

[arya2]

Looks good!

This might need to be merged manually, though it seems like the last release PR (#5513) was handled by Mergify. 🤷

[teor2345]

@Mergifyio update

[mergify]

update

✅ Branch has been successfully updated

[teor2345]

Looks good!

This might need to be merged manually, though it seems like the last release PR (#5513) was handled by Mergify. 🤷

If this PR is up to date with the main branch, then mergify does an in-place merge. So there's no extra PR to get rejected by the merge freeze. I guess we could add that to the instructions.

[dconnolly]

Looks good!
This might need to be merged manually, though it seems like the last release PR (#5513) was handled by Mergify. 🤷

If this PR is up to date with the main branch, then mergify does an in-place merge. So there's no extra PR to get rejected by the merge freeze. I guess we could add that to the instructions.

Looks like this is operating correctly: