diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md index b886446f3..936925636 100644 --- a/doc/book/src/SUMMARY.md +++ b/doc/book/src/SUMMARY.md @@ -2,11 +2,13 @@ [zcashd](README.md) - [User Documentation](user.md) + - [Platform Support](user/platform-support.md) - [Metrics](user/metrics.md) - [Deprecated Features](user/deprecation.md) - [Developer Documentation](dev.md) - [Rust in `zcashd`](dev/rust.md) - [Regtest tips and hints](dev/regtest.md) + - [Platform Tier Policy](dev/platform-tier-policy.md) - [Deprecation Procedure](dev/deprecation.md) - [Design](design.md) - [Chain state](design/chain-state.md) diff --git a/doc/book/src/dev/platform-tier-policy.md b/doc/book/src/dev/platform-tier-policy.md new file mode 100644 index 000000000..8e909e9a6 --- /dev/null +++ b/doc/book/src/dev/platform-tier-policy.md @@ -0,0 +1,136 @@ +# Platform Tier Policy + +## General + +ECC provides three tiers of platform support, modeled after the +[Rust Target Tier Policy](https://doc.rust-lang.org/stable/rustc/platform-tier-policy.html): + +- The Zcash developers provide no guarantees about tier 3 platforms; they exist in the + codebase, but may or may not build. +- ECC's continuous integration checks that tier 2 platforms will always build, but they + may or may not pass tests. +- ECC's continuous integration checks that tier 1 platforms will always build and pass + tests. + +Adding a new tier 3 platform imposes minimal requirements; we focus primarily on avoiding +disruption to other ongoing Zcash development. + +Tier 2 and tier 1 platforms place work on Zcash developers as a whole, to avoid breaking +the platform. The broader Zcash community may also feel more inclined to support +higher-tier platforms in their downstream uses of `zcashd` (though they are not obligated +to do so). Thus, these tiers require commensurate and ongoing efforts from the maintainers +of the platform, to demonstrate value and to minimize any disruptions to ongoing Zcash +development. + +This policy defines the requirements for accepting a proposed platform at a given level of +support. + +Each tier builds on all the requirements from the previous tier, unless overridden by a +stronger requirement. + +While these criteria attempt to document the policy, that policy still involves human +judgment. Platforms must fulfill the spirit of the requirements as well, as determined by +the judgment of the approving reviewers. Reviewers and team members evaluating platforms +and platform-specific patches should always use their own best judgment regarding the +quality of work, and the suitability of a platform for the Zcash project. Neither this +policy nor any decisions made regarding platforms shall create any binding agreement or +estoppel by any party. + +For a list of all supported platforms and their corresponding tiers ("tier 3", "tier 2", +or "tier 1"), see [Platform Support](../user/platform-support.md). + +The availability or tier of a platform in Zcash releases is not a hard stability guarantee +about the future availability or tier of that platform. Higher-level platform tiers are an +increasing commitment to the support of a platform, and we will take that commitment and +potential disruptions into account when evaluating the potential demotion or removal of a +platform that has been part of a stable release. The promotion or demotion of a platform +will not generally affect existing stable releases, only current development and future +releases. + +In this policy, the words "must" and "must not" specify absolute requirements that a +platform must meet to qualify for a tier. The words "should" and "should not" specify +requirements that apply in almost all cases, but for which the approving teams may grant +an exception for good reason. The word "may" indicates something entirely optional, and +does not indicate guidance or recommendations. This language is based on +[IETF RFC 2119](https://tools.ietf.org/html/rfc2119). + +## Tier 3 platform policy + +At this tier, ECC provides no official support for a platform, so we place minimal +requirements on the introduction of platforms. + +A proposed new tier 3 platform must be reviewed and approved by a member of the ECC core +team based on these requirements. + +- The platform must provide documentation for the Zcash community explaining how to build + for the platform, using cross-compilation if possible. If the platform supports running + binaries, or running tests (even if they do not pass), the documentation must explain + how to run such binaries or tests for the platform, using emulation if possible or + dedicated hardware if necessary. +- Tier 3 platforms must not impose burden on the authors of pull requests, or other + developers in the community, to maintain the platform. In particular, do not post + comments (automated or manual) on a PR that derail or suggest a block on the PR based on + a tier 3 platform. Do not send automated messages or notifications (via any medium, + including via @) to a PR author or others involved with a PR regarding a tier 3 + platform, unless they have opted into such messages. +- Patches adding or updating tier 3 platforms must not break any existing tier 2 or tier 1 + platform, and must not knowingly break another tier 3 platform without approval of the + ECC core team. + +If a tier 3 platform stops meeting these requirements, or the platform shows no signs of +activity and has not built for some time, or removing the platform would improve the +quality of the Zcash codebase, we may post a PR to remove it. + +## Tier 2 platform policy + +At this tier, the Zcash developers guarantee that a platform builds, and will reject +patches that fail to build for a platform. Thus, we place requirements that ensure the +platform will not block forward progress of the Zcash project. + +A proposed new tier 2 platform must be reviewed and approved by the ECC core team based +on these requirements. + +In addition, the ECC infrastructure team must approve the integration of the platform into +Continuous Integration (CI), and the tier 2 CI-related requirements. This review and +approval may take place in a PR adding the platform to CI, or simply by an infrastructure +team member reporting the outcome of a team discussion. + +- A tier 2 platform must have value to people other than its proponents. (It may still be + a niche platform, but it must not be exclusively useful for an inherently closed group.) +- A tier 2 platform must have a designated team of developers (the "platform maintainers") + supporting it, without the need for a paid support contract. +- The platform must not place undue burden on Zcash developers not specifically concerned + with that platform. Zcash developers are expected to not gratuitously break a tier 2 + platform, but are not expected to become experts in every tier 2 platform, and are not + expected to provide platform-specific implementations for every tier 2 platform. +- The platform must build reliably in CI, for all components that ECC's CI considers + mandatory. +- All requirements for tier 3 apply. + +A tier 2 platform may be demoted or removed if it no longer meets these requirements. + +## Tier 1 platform policy + +At this tier, the Zcash developers guarantee that a platform builds and passes all tests, +and will reject patches that fail to build or pass the test suite on a platform. We hold +tier 1 platforms to our highest standard of requirements. + +- Tier 1 platforms must have substantial, widespread interest within the Zcash community, + and must serve the ongoing needs of multiple production users of Zcash across multiple + organizations or projects. These requirements are subjective. A tier 1 platform may be + demoted or removed if it becomes obsolete or no longer meets this requirement. +- The platform must build and pass tests reliably in CI, for all components that ECC's CI + considers mandatory. +- Building the platform and running the test suite for the platform must not take + substantially longer than other platforms, and should not substantially raise the + maintenance burden of the CI infrastructure. +- Tier 1 platforms must not have a hard requirement for signed, verified, or otherwise + "approved" binaries. Developers must be able to build, run, and test binaries for the + platform on systems they control, or provide such binaries for others to run. (Doing so + may require enabling some appropriate "developer mode" on such systems, but must not + require the payment of any additional fee or other consideration, or agreement to any + onerous legal agreements.) +- All requirements for tier 2 apply. + +A tier 1 platform may be demoted or removed if it no longer meets these requirements but +still meets the requirements for a lower tier. diff --git a/doc/book/src/user/platform-support.md b/doc/book/src/user/platform-support.md new file mode 100644 index 000000000..b2e6fa4ed --- /dev/null +++ b/doc/book/src/user/platform-support.md @@ -0,0 +1,50 @@ +# Platform Support + +Support for different platforms (build "targets" and operating systems) are organised into +three tiers, each with a different set of guarantees. For more information on the policies +for targets at each tier, see the [Platform Tier Policy](../dev/platform-tier-policy.md). + +## Tier 1 + +Tier 1 platforms can be thought of as "guaranteed to work". ECC builds official binary +releases for each tier 1 platform, and automated testing ensures that each tier 1 platform +builds and passes tests after each change. + +"End of Support" dates are the latest currently-known date after which the platform will +be removed from tier 1. These dates are subject to change. + +| target | OS | End of Support | +| ----------------------- | ------------ | -------------- | +| `x86_64-pc-linux-gnu` | CentOS 8 | TBD | +| | Debian 10 | June 2024 | +| | Debian 11 | June 2026 | +| | Ubuntu 18.04 | April 2023 | +| | Ubuntu 20.04 | April 2025 | + +## Tier 2 + +Tier 2 platforms can be thought of as "guaranteed to build". ECC builds official binary +releases for each tier 2 platform, and automated builds ensure that each tier 2 platform +builds after each change. Automated tests are not always run so it's not guaranteed to +produce a working build, but tier 2 platforms often work to quite a good degree, and +patches are always welcome! + +"End of Support" dates are the latest currently-known date after which the platform will +be removed from tier 2. These dates are subject to change. + +| target | OS | End of Support | +| ----------------------- | ------------ | -------------- | +| N/A | + +## Tier 3 + +Tier 3 platforms are those for which the `zcashd` codebase has support, but ECC does not +require builds or tests to pass, so these may or may not work. Official builds are not +available. + +| target | OS | notes | +| ----------------------- | ------------ | ----- | +| `x86_64-pc-linux-gnu` | Arch | +| `x86_64-w64-mingw32` | Windows | 64-bit MinGW | +| `x86_64-apple-darwin16` | macOS 10.14+ | +| `aarch64-linux-gnu` | ARM64 Linux |