From 17c0bacca340b7505f8c784f67a85d832cede4ad Mon Sep 17 00:00:00 2001 From: teor Date: Fri, 21 Oct 2022 11:20:28 +1000 Subject: [PATCH] add(doc): Add draft audit process, and update some support docs (#5433) * Document parameter download workaround, particularly for macOS * Replace outdated build docs with a link to the README * Remove incorrectly rendered heading links * Add an initial draft audit process * Add dependency criteria --- README.md | 1 + book/src/dev/audit.md | 15 +++++++++++++++ book/src/dev/release-process.md | 18 +++++++++--------- book/src/user/install.md | 15 +-------------- 4 files changed, 26 insertions(+), 23 deletions(-) create mode 100644 book/src/dev/audit.md diff --git a/README.md b/README.md index 9eefabc1d..cee2009dc 100644 --- a/README.md +++ b/README.md @@ -227,6 +227,7 @@ So Zebra's state should always be valid, unless your OS or disk hardware is corr There are a few bugs in Zebra that we're still working on fixing: - Zebra requires Rust 1.63, due to [a compiler performance regression in Rust 1.64](https://github.com/ZcashFoundation/zebra/issues/5091) + - If Zebra fails downloading the Zcash parameters, use [the Zcash parameters download script](https://github.com/zcash/zcash/blob/master/zcutil/fetch-params.sh) instead. This script might be needed on macOS, even with Rust 1.63. - No Windows support [#3801](https://github.com/ZcashFoundation/zebra/issues/3801) - We used to test with Windows Server 2019, but not anymore; see issue for details diff --git a/book/src/dev/audit.md b/book/src/dev/audit.md new file mode 100644 index 000000000..73827e7c0 --- /dev/null +++ b/book/src/dev/audit.md @@ -0,0 +1,15 @@ +# Zebra audits + +In addition to our normal [release process](https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/release-process.md], we do these steps to prepare for an audit: +1. [Tag a release candidate](https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/release-process.md#preview-releases) with the code to be audited +2. Declare a feature and fix freeze: non-essential changes must wait until after the audit, new features must be behind a [Rust feature flag](https://doc.rust-lang.org/cargo/reference/features.html) +3. Prepare a list of dependencies that are [in scope, partially in scope, and out of scope](https://github.com/ZcashFoundation/zebra/issues/5214). Audits focus on: + - production Rust code that the Zcash Foundation has written, or is responsible for + - consensus-critical and security-critical code + - code that hasn't already been audited + +Some code might require specialist audits, for example, consensus-critical cryptographic code. + +The audit tag and freeze allow us to create an audit branch, and merge it into the `main` branch easily. Audit branches are optional, we'll make a decision based on: +- if the auditors want a separate branch to review recommended changes, and +- the complexity of the changes. diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md index 4b4a8c524..fe026435f 100644 --- a/book/src/dev/release-process.md +++ b/book/src/dev/release-process.md @@ -8,7 +8,7 @@ Before reading, you should understand [Semantic Versioning](https://semver.org/s -## Zebra versioning {#zebra-versioning} +## Zebra versioning Zebra version numbers show the impact of the changes in a release. They are composed of three parts: `major.minor.patch`. For example, version `3.1.11` indicates major version 3, minor version 1, and patch level 11. @@ -31,7 +31,7 @@ The pre-release version is denoted by appending a hyphen and a series of dot sep -### Supported Releases {#supported-releases} +### Supported Releases Older Zebra versions are always supported until the next Zebra major, minor or patch release. Initially, we can only guarantee support for the latest Zebra release. We might be able to provide support for earlier releases, or we might ask you to upgrade to the latest release. @@ -42,7 +42,7 @@ Older Zebra versions that only support previous network upgrades will never be s -### Supported update paths {#supported-update-paths} +### Supported update paths You can update to any version of Zebra, provided that the following criteria are met: @@ -53,7 +53,7 @@ See [Keeping Up-to-Date](guide/updating "Updating your projects") for more infor -### Preview releases {#preview-releases} +### Preview releases We let you preview what's coming by providing Release Candidate \(`rc`\) pre-releases for some major releases: @@ -62,7 +62,7 @@ We let you preview what's coming by providing Release Candidate \(`rc`\) pre-rel | Beta | The release that is under active development and testing. The beta release is indicated by a release tag appended with the `-beta` identifier, such as `8.1.0-beta.0`. | | Release candidate | A release for final testing of new features. A release candidate is indicated by a release tag appended with the `-rc` identifier, such as version `8.1.0-rc.0`. | -### Distribution tags {#distribution-tags} +### Distribution tags Zebras's tagging relates directly to versions published on Docker. We will reference these [Docker Hub distribution tags](https://hub.docker.com/r/zfnd/zebra/tags) throughout: @@ -72,7 +72,7 @@ Zebras's tagging relates directly to versions published on Docker. We will refer | beta | The most recent pre-release version of Zebra for testing. May not always exist. | | rc | The most recent release candidate of Zebra, meant to become a stable version. May not always exist. | -### Feature Flags {#feature-flags} +### Feature Flags To keep the `main` branch in a releasable state, experimental features must be gated behind a [Rust feature flag](https://doc.rust-lang.org/cargo/reference/features.html). Breaking changes should also be gated behind a feature flag, unless the team decides they are urgent. @@ -80,7 +80,7 @@ Breaking changes should also be gated behind a feature flag, unless the team dec -## Release frequency {#release-frequency} +## Release frequency We work toward a regular schedule of releases, so that you can plan and coordinate your updates with the continuing evolution of Zebra. @@ -100,7 +100,7 @@ This cadence of releases gives eager developers access to new features as soon a -## Deprecation practices {#deprecation-practices} +## Deprecation practices Sometimes "breaking changes", such as the removal of support for RPCs, APIs, and features, are necessary to: @@ -125,6 +125,6 @@ To help ensure that you have sufficient time and a clear path to update, this is -## Release candidate & release process {#release-process} +## Release candidate & release process Our release checklist is available as a template, which defines each step our team needs to follow to create a new pre-release or release, and to also build and push the binaries to the official channels [Release Checklist Template](https://github.com/ZcashFoundation/zebra/blob/main/.github/PULL_REQUEST_TEMPLATE/release-checklist.md). diff --git a/book/src/user/install.md b/book/src/user/install.md index 8134d5935..f4534b1bc 100644 --- a/book/src/user/install.md +++ b/book/src/user/install.md @@ -1,19 +1,6 @@ # Installing Zebra -`zebrad` is still under development, so there is no supported packaging or -install mechanism. To run `zebrad`, follow the instructions to compile `zebrad` -for your platform: - -1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install). - - Using `rustup` installs the stable Rust toolchain, which `zebrad` targets. -2. Install Zebra's build dependencies: - - **libclang:** the `libclang`, `libclang-dev`, `llvm`, or `llvm-dev` packages, depending on your package manager - - **clang** or another C++ compiler: `g++`, `Xcode`, or `MSVC` -3. Run `cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-rc.0 zebrad` -4. Run `zebrad start` (see [Running Zebra](run.md) for more information) - -If you're interested in testing out `zebrad` please feel free, but keep in mind -that there is a lot of key functionality still missing. +Follow the [Docker or compilation instructions in the README](https://github.com/ZcashFoundation/zebra#getting-started). #### Build Troubleshooting