From 9530bf522bb80dd8927289cd6ecbf00f23f6b4ae Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Thu, 16 Jun 2022 18:45:20 -0400 Subject: [PATCH 1/9] ci(docs): test `cargo doc` warnings and errors --- .github/workflows/lint.yml | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 3b74716df11..e5a97e0efdf 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -95,7 +95,7 @@ jobs: with: persist-credentials: false - - uses: actions-rs/toolchain@v1.0.1 + - uses: actions-rs/toolchain@v1.0.6 with: toolchain: stable components: rustfmt @@ -108,6 +108,31 @@ jobs: command: fmt args: --all -- --check + docs: + name: Rust doc + timeout-minutes: 30 + runs-on: ubuntu-latest + needs: changed-files + if: ${{ needs.changed-files.outputs.rust == 'true' }} + + steps: + - uses: actions/checkout@v3.0.2 + with: + persist-credentials: false + + - uses: actions-rs/toolchain@v1.0.6 + with: + profile: minimal + toolchain: stable + components: docs + override: true + + - uses: Swatinem/rust-cache@v1 + - uses: actions-rs/cargo@v1.0.3 + with: + command: doc + args: --no-deps --document-private-items --all-features + actionlint: runs-on: ubuntu-latest continue-on-error: true From 6f56ed7698cd2da89bdd8ea34be854f73ff5d186 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Thu, 16 Jun 2022 19:12:11 -0400 Subject: [PATCH 2/9] ci(docs): remove minimal profile --- .github/workflows/lint.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index e5a97e0efdf..4308a925e5b 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -122,7 +122,6 @@ jobs: - uses: actions-rs/toolchain@v1.0.6 with: - profile: minimal toolchain: stable components: docs override: true From b6067156587bc5c14475bc65d9dec8599967928c Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Thu, 16 Jun 2022 19:15:12 -0400 Subject: [PATCH 3/9] ci(docs): revert minimal and fix component name --- .github/workflows/lint.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 4308a925e5b..046e8a23c83 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -122,8 +122,9 @@ jobs: - uses: actions-rs/toolchain@v1.0.6 with: + profile: minimal toolchain: stable - components: docs + components: doc override: true - uses: Swatinem/rust-cache@v1 From 44b7cfe0f6de0874646eb5faa1ab86870f051f1d Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Thu, 16 Jun 2022 19:40:10 -0400 Subject: [PATCH 4/9] ci(docs): try cargo doc alone --- .github/workflows/lint.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 046e8a23c83..9c389b98136 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -122,12 +122,10 @@ jobs: - uses: actions-rs/toolchain@v1.0.6 with: - profile: minimal toolchain: stable - components: doc + profile: minimal override: true - - uses: Swatinem/rust-cache@v1 - uses: actions-rs/cargo@v1.0.3 with: command: doc From 05dcde30ea9699bda16b3772b6ee5918dd307f17 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Tue, 16 Aug 2022 22:34:28 -0400 Subject: [PATCH 5/9] docs(release): add versioning and releases information --- book/src/dev/alpha-release-criteria.md | 63 --------- book/src/dev/release-process.md | 170 +++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 63 deletions(-) delete mode 100644 book/src/dev/alpha-release-criteria.md create mode 100644 book/src/dev/release-process.md diff --git a/book/src/dev/alpha-release-criteria.md b/book/src/dev/alpha-release-criteria.md deleted file mode 100644 index c628490c29b..00000000000 --- a/book/src/dev/alpha-release-criteria.md +++ /dev/null @@ -1,63 +0,0 @@ -# Go/No-Go Release Criteria - -## Alpha Release - -In the first alpha release, we want Zebra to participate in the network and replicate the Zcash chain state. -We also want to validate proof of work and the transaction merkle tree, and serve blocks to peers. - -### System Requirements - -Our CI tests that Zebra builds, passes its tests, and syncs on recent Ubuntu Linux, macOS, and Windows. - -See the [README](https://github.com/ZcashFoundation/zebra/blob/main/README.md#system-requirements) -for specific system requirements. - -### Build Requirements - -Our CI builds Zebra with: -* Rust stable -* recent llvm -* recent clang -* recent libclang - -### Supported Platforms - -While Zebra is still in alpha, we don't guarantee support for any particular platforms. - -But you'll probably get the best results with a recent Ubuntu Linux, or the other platforms that our CI runs on. - -### Go/No-Go Status: ⚠️ - -_Last updated: December 7 2020_ - -- `zebrad` Functionality - - `zebrad` can sync to mainnet tip - - ⚠️ under excellent network conditions (within 2 - 5 hours) - - _reasonable and sub-optimal network conditions are not yet supported_ - - `zebrad` can stay within a few blocks of the mainnet tip after the initial sync - - ⚠️ under excellent network conditions - - _reasonable and sub-optimal network conditions are not yet supported_ - - ✅ `zebrad` can validate proof of work - - ✅ `zebrad` can validate the transaction merkle tree - - ⚠️ `zebrad` can serve blocks to peers - - ✅ The hard-coded [checkpoint lists](https://github.com/ZcashFoundation/zebra/tree/main/zebra-consensus/src/checkpoint) are up-to-date -- `zebrad` Performance - - ✅ `zebrad` functionality works on platforms that meet its system requirements -- Testing - - ⚠️ CI Passes - - ✅ Unit tests pass reliably - - ✅ Property tests pass reliably - - ⚠️ Acceptance tests pass reliably - - ✅ Each Zebra crate [builds individually](https://github.com/ZcashFoundation/zebra/issues/1364) -- Implementation and Launch - - ✅ All [release blocker bugs](https://github.com/ZcashFoundation/zebra/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22First+Alpha+Release%22+label%3AC-bug) have been fixed - - ✅ The list of [known serious issues](https://github.com/ZcashFoundation/zebra#known-issues) is up to date - - ✅ The Zebra crate versions are up to date - - ⚠️ Users can access [the documentation to deploy `zebrad` nodes](https://github.com/ZcashFoundation/zebra#getting-started) -- User Experience - - ✅ Build completes within 40 minutes in Zebra's CI - - ✅ Unused dependencies have been removed (use `cargo-udeps`) - - ✅ `zebrad` executes normally - - ✅ `zebrad`'s default logging works reasonably well in a terminal - - ✅ panics, error logs, and warning logs are rare on mainnet - - ✅ known panics, errors and warnings have open tickets diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md new file mode 100644 index 00000000000..125b87cde8c --- /dev/null +++ b/book/src/dev/release-process.md @@ -0,0 +1,170 @@ +# Zebra versioning and releases + +This document contains the practices that we follow to provide you with a leading-edge application, balanced and with stability. +We strive to ensure that future changes are always introduced in a predictable way. +We want everyone who depends on Zebra to know when and how new features are added, and to be well-prepared when obsolete ones are removed. + + + +## Zebra versioning + +Zebra version numbers indicate the level of changes that are introduced by the release. +This use of [semantic versioning](https://semver.org/ "Semantic Versioning Specification") helps you understand the potential impact of updating to a new version. + +Zebra version numbers have three parts: `major.minor.patch`. +For example, version `3.1.11` indicates major version 3, minor version 1, and patch level 11. + +The version number is incremented based on the level of change included in the release. + +
+ +**NOTE**:
+As Zebra is in a `pre-release` state (is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version). +The pre-release version is denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. + +
+ +| Level of change | Details | +|:--- |:--- | +| Major release | Contains significant new features, and commonly correspond to network upgrades; some technical assistance is expected during the update. When updating to a new major release, you might need to . | +| Minor release | Contains new smaller features. Minor releases are meant to be fully backward-compatible, but may include breaking changes to public APIs. No technical assistance is expected during update. | +| Patch release | Low risk, bug fix release. No technical assistance is expected during update. | + + + +### Supported update paths + +You can update to any version of Zebra, provided that the following criteria are met: + +* The version you want to update *to* is supported. +* The version you want to update *from* is within one major version of the version you want to + upgrade to. + +See [Keeping Up-to-Date](guide/updating "Updating your projects") for more information about updating your Zebra projects to the most recent version. + + + +### Preview releases + +We let you preview what's coming by providing "Next" and Release Candidates \(`rc`\) pre-releases for each major and minor release: + +| Pre-release type | Details | +|:--- |:--- | +| Next | The release that is under active development and testing. The next release is indicated by a release tag appended with the `-next` identifier, such as `8.1.0-next.0`. | +| Release candidate | A release that is feature complete and in final testing. A release candidate is indicated by a release tag appended with the `-rc` identifier, such as version `8.1.0-rc.0`. | + +The latest `next` or `rc` pre-release version of the documentation is available at [next.Zebra.io](https://next.Zebra.io). + + + +## 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. + +
+ +Dates are offered as general guidance and are subject to change. + +
+ +In general, expect the following release cycle: + +* A major once a network upgrade is required +* 1-3 minor releases for each major release +* A patch release build almost semiweekly + +This cadence of releases gives eager developers access to new features as soon as they are fully developed and pass through our code review and integration testing processes, while maintaining the stability and reliability of the platform for production users that prefer to receive features after they have been validated by Zcash and other developers that use the pre-release builds. + + + +## Deprecation practices + +Sometimes "breaking changes", such as the removal of support for select APIs and features, are necessary to innovate and stay current with new best practices, changing dependencies, or changes in the \(blockchain\) itself. + +To make these transitions as straightforward as possible, we make these commitments to you: + +* We work hard to minimize the number of breaking changes and to provide migration tools, when possible +* We follow the deprecation policy described here, so you have time to update your applications to the latest APIs and best practices + +To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: + +| Deprecation stages | Details | +|:--- |:--- | +| Announcement | We announce deprecated APIs and features in the [change log](https://github.com/ZcashFoundation/zebra/blob/main/CHANGELOG.md "Zebra change log"). Deprecated APIs appear in the [documentation](missing-link) with ~~strikethrough~~. When we announce a deprecation, we also announce a recommended update path. | +| Deprecation period | When an API or a feature is deprecated, it is still present in the next major release. After that, deprecated APIs and features are candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature happens only in major release. Until a deprecated API or feature is removed, it is maintained according to the Tier 1 support policy, meaning that only critical and security issues are fixed. | +| crate dependencies | We only make crate dependency updates that require changes to your applications in a major release. In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version. This means that during minor Zebra releases, crate dependency updates within Zebra applications and libraries are optional. | + + + +## Release candidate & release process + +Identify the commit from which the release stabilization branch will be made. +Release stabilization branches are used so that development can proceed +unblocked on the `master` branch during the release candidate testing and +bug-fixing process. By convention, release stabilization branches are named +`version-X.Y.0` where `X` and `Y` are the major and minor versions for the +release. + +### Create the release stabilization branch + +**\** + +### Create the release candidate branch + +**\** + +### Make a tag for the tip of the release candidate branch + +**\** + +## Make and deploy deterministic builds + +**\** + +## Add release notes to GitHub + +## Go/No-Go Status: ⚠️ + +* `zebrad` Functionality + * `zebrad` can sync to mainnet tip + * ⚠️ under excellent network conditions (within 2 - 5 hours) + * _reasonable and sub-optimal network conditions are not yet supported_ + * `zebrad` can stay within a few blocks of the mainnet tip after the initial sync + * ⚠️ under excellent network conditions + * _reasonable and sub-optimal network conditions are not yet supported_ + * ✅ `zebrad` can validate proof of work + * ✅ `zebrad` can validate the transaction merkle tree + * ⚠️ `zebrad` can serve blocks to peers + * ✅ The hard-coded [checkpoint lists](https://github.com/ZcashFoundation/zebra/tree/main/zebra-consensus/src/checkpoint) are up-to-date +* `zebrad` Performance + * ✅ `zebrad` functionality works on platforms that meet its system requirements +* Testing + * ⚠️ CI Passes + * ✅ Unit tests pass reliably + * ✅ Property tests pass reliably + * ⚠️ Acceptance tests pass reliably + * ✅ Each Zebra crate [builds individually](https://github.com/ZcashFoundation/zebra/issues/1364) +* Implementation and Launch + * ✅ All [release blocker bugs](https://github.com/ZcashFoundation/zebra/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22First+Alpha+Release%22+label%3AC-bug) have been fixed + * ✅ The list of [known serious issues](https://github.com/ZcashFoundation/zebra#known-issues) is up to date + * ✅ The Zebra crate versions are up to date + * ⚠️ Users can access [the documentation to deploy `zebrad` nodes](https://github.com/ZcashFoundation/zebra#getting-started) +* User Experience + * ✅ Build completes within 40 minutes in Zebra's CI + * ✅ Unused dependencies have been removed (use `cargo-udeps`) + * ✅ `zebrad` executes normally + * ✅ `zebrad`'s default logging works reasonably well in a terminal + * ✅ panics, error logs, and warning logs are rare on mainnet + * ✅ known panics, errors and warnings have open tickets + +## Post Release Task List + +### Merge the release stabilization branch + + + + + + + +@reviewed **\** From 08e27fb69bae33407a2bfdea86c7759c6f5e5ab1 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Mon, 29 Aug 2022 18:05:12 -0400 Subject: [PATCH 6/9] dosc(release): apply suggestions from code review Co-authored-by: teor --- book/src/dev/release-process.md | 39 +++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md index 125b87cde8c..5b6ba2e1bb6 100644 --- a/book/src/dev/release-process.md +++ b/book/src/dev/release-process.md @@ -26,10 +26,23 @@ The pre-release version is denoted by appending a hyphen and a series of dot sep | Level of change | Details | |:--- |:--- | -| Major release | Contains significant new features, and commonly correspond to network upgrades; some technical assistance is expected during the update. When updating to a new major release, you might need to . | -| Minor release | Contains new smaller features. Minor releases are meant to be fully backward-compatible, but may include breaking changes to public APIs. No technical assistance is expected during update. | +| Major release | Contains significant new features, and commonly correspond to network upgrades; some technical assistance may be needed during the update. When updating to a major release, you may need to follow the specific upgrade instructions provided in the release notes. | +| Minor release | Contains new smaller features. Minor releases are should be fully backward-compatible. No technical assistance is expected during update. | | Patch release | Low risk, bug fix release. No technical assistance is expected during update. | + + +### 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. + +Our support periods will be extended as we gain experience with supporting Zebra releases. + +Older Zebra versions that only support previous network upgrades will never be supported, because they are operating on an unsupported Zcash chain fork. + ### Supported update paths @@ -46,7 +59,7 @@ See [Keeping Up-to-Date](guide/updating "Updating your projects") for more infor ### Preview releases -We let you preview what's coming by providing "Next" and Release Candidates \(`rc`\) pre-releases for each major and minor release: +We let you preview what's coming by providing Release Candidate \(`rc`\) pre-releases for some major releases: | Pre-release type | Details | |:--- |:--- | @@ -69,9 +82,9 @@ Dates are offered as general guidance and are subject to change. In general, expect the following release cycle: -* A major once a network upgrade is required -* 1-3 minor releases for each major release -* A patch release build almost semiweekly +* A major release for each network upgrade, and whenever there are breaking changes to Zebra +* Minor releases for significant new Zebra features +* A patch release every few weeks This cadence of releases gives eager developers access to new features as soon as they are fully developed and pass through our code review and integration testing processes, while maintaining the stability and reliability of the platform for production users that prefer to receive features after they have been validated by Zcash and other developers that use the pre-release builds. @@ -79,20 +92,24 @@ This cadence of releases gives eager developers access to new features as soon a ## Deprecation practices -Sometimes "breaking changes", such as the removal of support for select APIs and features, are necessary to innovate and stay current with new best practices, changing dependencies, or changes in the \(blockchain\) itself. +Sometimes "breaking changes", such as the removal of support for RPCs, APIs, and features, are necessary to: +* add new Zebra features, +* improve Zebra performance or reliability, +* stay current with changing dependencies, or +* implement changes in the \(blockchain\) itself. To make these transitions as straightforward as possible, we make these commitments to you: * We work hard to minimize the number of breaking changes and to provide migration tools, when possible -* We follow the deprecation policy described here, so you have time to update your applications to the latest APIs and best practices +* We follow the deprecation policy described here, so you have time to update your applications to the latest Zebra binaries, RPCs and APIs To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: | Deprecation stages | Details | |:--- |:--- | -| Announcement | We announce deprecated APIs and features in the [change log](https://github.com/ZcashFoundation/zebra/blob/main/CHANGELOG.md "Zebra change log"). Deprecated APIs appear in the [documentation](missing-link) with ~~strikethrough~~. When we announce a deprecation, we also announce a recommended update path. | -| Deprecation period | When an API or a feature is deprecated, it is still present in the next major release. After that, deprecated APIs and features are candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature happens only in major release. Until a deprecated API or feature is removed, it is maintained according to the Tier 1 support policy, meaning that only critical and security issues are fixed. | -| crate dependencies | We only make crate dependency updates that require changes to your applications in a major release. In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version. This means that during minor Zebra releases, crate dependency updates within Zebra applications and libraries are optional. | +| Announcement | We announce deprecated RPCs and features in the [change log](https://github.com/ZcashFoundation/zebra/blob/main/CHANGELOG.md "Zebra change log"). When we announce a deprecation, we also announce a recommended update path. | +| Deprecation period | When a RPC or a feature is deprecated, it is still present until the next major release. A deprecation can be announced in any release, but the removal of a deprecated RPC or feature happens only in major release. Until a deprecated RPC or feature is removed, it is maintained according to the Tier 1 support policy, meaning that only critical and security issues are fixed. | +| Rust APIs | The Rust APIs of the Zebra crates are unstable and unsupported. Use the `zebrad` commands or JSON-RPCs to interact with Zebra. | From 3ea36c64f3e5a9320ecbdcd4b0361bfc159e1cdd Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Wed, 14 Sep 2022 16:42:28 -0400 Subject: [PATCH 7/9] docs(release): apply multiple fixes from review --- book/src/dev/release-process.md | 76 ++------------------------------- 1 file changed, 3 insertions(+), 73 deletions(-) diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md index 5b6ba2e1bb6..130c2267c0e 100644 --- a/book/src/dev/release-process.md +++ b/book/src/dev/release-process.md @@ -63,11 +63,9 @@ We let you preview what's coming by providing Release Candidate \(`rc`\) pre-rel | Pre-release type | Details | |:--- |:--- | -| Next | The release that is under active development and testing. The next release is indicated by a release tag appended with the `-next` identifier, such as `8.1.0-next.0`. | +| 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 that is feature complete and in final testing. A release candidate is indicated by a release tag appended with the `-rc` identifier, such as version `8.1.0-rc.0`. | -The latest `next` or `rc` pre-release version of the documentation is available at [next.Zebra.io](https://next.Zebra.io). - ## Release frequency @@ -93,6 +91,7 @@ This cadence of releases gives eager developers access to new features as soon a ## Deprecation practices Sometimes "breaking changes", such as the removal of support for RPCs, APIs, and features, are necessary to: + * add new Zebra features, * improve Zebra performance or reliability, * stay current with changing dependencies, or @@ -115,73 +114,4 @@ To help ensure that you have sufficient time and a clear path to update, this is ## Release candidate & release process -Identify the commit from which the release stabilization branch will be made. -Release stabilization branches are used so that development can proceed -unblocked on the `master` branch during the release candidate testing and -bug-fixing process. By convention, release stabilization branches are named -`version-X.Y.0` where `X` and `Y` are the major and minor versions for the -release. - -### Create the release stabilization branch - -**\** - -### Create the release candidate branch - -**\** - -### Make a tag for the tip of the release candidate branch - -**\** - -## Make and deploy deterministic builds - -**\** - -## Add release notes to GitHub - -## Go/No-Go Status: ⚠️ - -* `zebrad` Functionality - * `zebrad` can sync to mainnet tip - * ⚠️ under excellent network conditions (within 2 - 5 hours) - * _reasonable and sub-optimal network conditions are not yet supported_ - * `zebrad` can stay within a few blocks of the mainnet tip after the initial sync - * ⚠️ under excellent network conditions - * _reasonable and sub-optimal network conditions are not yet supported_ - * ✅ `zebrad` can validate proof of work - * ✅ `zebrad` can validate the transaction merkle tree - * ⚠️ `zebrad` can serve blocks to peers - * ✅ The hard-coded [checkpoint lists](https://github.com/ZcashFoundation/zebra/tree/main/zebra-consensus/src/checkpoint) are up-to-date -* `zebrad` Performance - * ✅ `zebrad` functionality works on platforms that meet its system requirements -* Testing - * ⚠️ CI Passes - * ✅ Unit tests pass reliably - * ✅ Property tests pass reliably - * ⚠️ Acceptance tests pass reliably - * ✅ Each Zebra crate [builds individually](https://github.com/ZcashFoundation/zebra/issues/1364) -* Implementation and Launch - * ✅ All [release blocker bugs](https://github.com/ZcashFoundation/zebra/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22First+Alpha+Release%22+label%3AC-bug) have been fixed - * ✅ The list of [known serious issues](https://github.com/ZcashFoundation/zebra#known-issues) is up to date - * ✅ The Zebra crate versions are up to date - * ⚠️ Users can access [the documentation to deploy `zebrad` nodes](https://github.com/ZcashFoundation/zebra#getting-started) -* User Experience - * ✅ Build completes within 40 minutes in Zebra's CI - * ✅ Unused dependencies have been removed (use `cargo-udeps`) - * ✅ `zebrad` executes normally - * ✅ `zebrad`'s default logging works reasonably well in a terminal - * ✅ panics, error logs, and warning logs are rare on mainnet - * ✅ known panics, errors and warnings have open tickets - -## Post Release Task List - -### Merge the release stabilization branch - - - - - - - -@reviewed **\** +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). From e3a23b09b120add5f1d60a09c61edf9e24300255 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Wed, 14 Sep 2022 16:57:35 -0400 Subject: [PATCH 8/9] docs(release): allow more flexibility with release cycles --- book/src/dev/release-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md index 130c2267c0e..0cf4b1476fc 100644 --- a/book/src/dev/release-process.md +++ b/book/src/dev/release-process.md @@ -80,8 +80,8 @@ Dates are offered as general guidance and are subject to change. In general, expect the following release cycle: -* A major release for each network upgrade, and whenever there are breaking changes to Zebra -* Minor releases for significant new Zebra features +* A major release for each network upgrade, whenever there are breaking changes to Zebra (by API, severe bugs or other kind of upgrades) +* Minor releases for significant new Zebra features or severe bug fixes * A patch release every few weeks This cadence of releases gives eager developers access to new features as soon as they are fully developed and pass through our code review and integration testing processes, while maintaining the stability and reliability of the platform for production users that prefer to receive features after they have been validated by Zcash and other developers that use the pre-release builds. From c1a249729f901f4159a4fff481a985e4e0adf7ec Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Wed, 14 Sep 2022 21:27:24 -0400 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: teor --- book/src/dev/release-process.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/book/src/dev/release-process.md b/book/src/dev/release-process.md index 0cf4b1476fc..e536693f8fe 100644 --- a/book/src/dev/release-process.md +++ b/book/src/dev/release-process.md @@ -27,7 +27,7 @@ The pre-release version is denoted by appending a hyphen and a series of dot sep | Level of change | Details | |:--- |:--- | | Major release | Contains significant new features, and commonly correspond to network upgrades; some technical assistance may be needed during the update. When updating to a major release, you may need to follow the specific upgrade instructions provided in the release notes. | -| Minor release | Contains new smaller features. Minor releases are should be fully backward-compatible. No technical assistance is expected during update. | +| Minor release | Contains new smaller features. Minor releases are should be fully backward-compatible. No technical assistance is expected during update. If you want to use the new features in a minor release, you might need to follow the instructions in the release notes. | | Patch release | Low risk, bug fix release. No technical assistance is expected during update. | @@ -64,7 +64,7 @@ We let you preview what's coming by providing Release Candidate \(`rc`\) pre-rel | Pre-release type | Details | |:--- |:--- | | 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 that is feature complete and in final testing. A release candidate is indicated by a release tag appended with the `-rc` identifier, such as version `8.1.0-rc.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`. | @@ -101,6 +101,7 @@ To make these transitions as straightforward as possible, we make these commitme * We work hard to minimize the number of breaking changes and to provide migration tools, when possible * We follow the deprecation policy described here, so you have time to update your applications to the latest Zebra binaries, RPCs and APIs +* If a feature has critical security or reliability issues, and we need to remove it as soon as possible, we will explain why at the top of the release notes To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: @@ -108,7 +109,7 @@ To help ensure that you have sufficient time and a clear path to update, this is |:--- |:--- | | Announcement | We announce deprecated RPCs and features in the [change log](https://github.com/ZcashFoundation/zebra/blob/main/CHANGELOG.md "Zebra change log"). When we announce a deprecation, we also announce a recommended update path. | | Deprecation period | When a RPC or a feature is deprecated, it is still present until the next major release. A deprecation can be announced in any release, but the removal of a deprecated RPC or feature happens only in major release. Until a deprecated RPC or feature is removed, it is maintained according to the Tier 1 support policy, meaning that only critical and security issues are fixed. | -| Rust APIs | The Rust APIs of the Zebra crates are unstable and unsupported. Use the `zebrad` commands or JSON-RPCs to interact with Zebra. | +| Rust APIs | The Rust APIs of the Zebra crates are currently unstable and unsupported. Use the `zebrad` commands or JSON-RPCs to interact with Zebra. |