From 9f6b7ab85aada5e2eb41e3e65e7884239217fbd8 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 12 May 2022 10:58:07 +0000 Subject: [PATCH 1/3] book: Add platform support information and tier policy --- doc/book/src/SUMMARY.md | 2 + doc/book/src/dev/platform-tier-policy.md | 136 +++++++++++++++++++++++ doc/book/src/user/platform-support.md | 50 +++++++++ 3 files changed, 188 insertions(+) create mode 100644 doc/book/src/dev/platform-tier-policy.md create mode 100644 doc/book/src/user/platform-support.md 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 | From a94b26f029f0f485f5d918c9e3c68758ff237c16 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 24 May 2022 13:11:12 +0000 Subject: [PATCH 2/3] book: Capitalize key words in platform tier policy --- doc/book/src/dev/platform-tier-policy.md | 58 ++++++++++++------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/doc/book/src/dev/platform-tier-policy.md b/doc/book/src/dev/platform-tier-policy.md index 8e909e9a6..b4149f864 100644 --- a/doc/book/src/dev/platform-tier-policy.md +++ b/doc/book/src/dev/platform-tier-policy.md @@ -47,10 +47,10 @@ platform that has been part of a stable release. The promotion or demotion of a 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 +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 +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). @@ -59,27 +59,27 @@ does not indicate guidance or recommendations. This language is based on 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 +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 +- 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 + 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 +- 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 +- 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. +quality of the Zcash codebase, we MAY post a PR to remove it. ## Tier 2 platform policy @@ -87,27 +87,27 @@ At this tier, the Zcash developers guarantee that a platform builds, and will re 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 +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 +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 +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") +- 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 +- 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 +- 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. +A tier 2 platform MAY be demoted or removed if it no longer meets these requirements. ## Tier 1 platform policy @@ -115,22 +115,22 @@ At this tier, the Zcash developers guarantee that a platform builds and passes a 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 +- 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 +- 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 +- 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 +- 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 + 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 +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. From dd51f0995e95cd8bbfc305568e2a3125fc740382 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 24 May 2022 13:40:15 +0000 Subject: [PATCH 3/3] book: Add FreeBSD to tier 3 platforms list --- doc/book/src/user/platform-support.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/book/src/user/platform-support.md b/doc/book/src/user/platform-support.md index b2e6fa4ed..996bb818e 100644 --- a/doc/book/src/user/platform-support.md +++ b/doc/book/src/user/platform-support.md @@ -45,6 +45,7 @@ available. | target | OS | notes | | ----------------------- | ------------ | ----- | | `x86_64-pc-linux-gnu` | Arch | +| `x86_64-unknown-freebsd`| FreeBSD | | `x86_64-w64-mingw32` | Windows | 64-bit MinGW | | `x86_64-apple-darwin16` | macOS 10.14+ | | `aarch64-linux-gnu` | ARM64 Linux |