docs(release): add support Tiers and supported platforms per Tier (#4773)

* docs: include target tier policies

This documentation is based on Rust supported platforms and tiers, and adapted to Zebra

* docs: add supported platforms by Tier

* docs(release): remove references to use RFCs

* docs(release): adapt teams to ZFND reality

* docs(release): remove text that might generate confusion

* docs(release): refactor general wording to our needs

* docs(release): update wording in supported platforms

* docs: clarify we're not having build artifacts for Tier 2

* docs: remove stub requirements

* docs: tidy up

* docs: last fixes

* docs(platforms): improve overall documentation

* docs: remove legal language

* docs: rewording tier 3 summary

* Update book/src/user/supported-platforms.md

Co-authored-by: teor <teor@riseup.net>

* docs: remove reference to core engineering team

* fix(docs): make rust version a separate column

* tiny fix

* If a supported platform isn't pinned to a specific release, link to the latest release

* Add space for readability

* Clarify some phrasing

* Remove Rust-compiler specific language, replace with consensus rules and features

* Update book/src/user/supported-platforms.md

Co-authored-by: teor <teor@riseup.net>

* Update book/src/user/target-tier-policies.md

Co-authored-by: teor <teor@riseup.net>

* Update book/src/user/target-tier-policies.md

Co-authored-by: teor <teor@riseup.net>

* Update book/src/user/target-tier-policies.md

Co-authored-by: teor <teor@riseup.net>

Co-authored-by: teor <teor@riseup.net>

book/src/user/requirements.md

@@ -1,6 +1,7 @@
 # System Requirements
 
 We usually build `zebrad` on systems with:
+
 - 2+ CPU cores
 - 7+ GB RAM
 - 14+ GB of disk space
@@ -9,11 +10,13 @@ On many-core machines (like, 32-core) the build is very fast; on 2-core machines
 it's less fast.
 
 We continuously test that our builds and tests pass on:
+
 - macOS Big Sur 11.0
 - Ubuntu 18.04 / the latest LTS
 - Debian Buster
 
 We usually run `zebrad` on systems with:
+
 - 4+ CPU cores
 - 16+ GB RAM
 - 50GB+ available disk space for finalized state
@@ -31,6 +34,7 @@ Compile Zebra with `--features sentry` to monitor it using Sentry in production.
 ## Lightwalletd Test Requirements
 
 To test Zebra's `lightwalletd` RPC methods:
+
 - compile Zebra with the `--features lightwalletd-grpc-tests`
 - install a `lightwalletd` binary
   - Zebra's tests currently target [adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd)

book/src/user/supported-platforms.md

@@ -0,0 +1,49 @@
+# Platform Support
+
+Support for different platforms are organized into three tiers, each with a
+different set of guarantees. For more information on the policies for platforms
+at each tier, see the [Platform Tier Policy](platform-tier-policy.md).
+
+Platforms are identified by their Rust "target triple" which is a string composed by
+`<machine>-<vendor>-<operating system>`.
+
+## Tier 1
+
+Tier 1 platforms can be thought of as "guaranteed to work". The Zebra project
+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.
+
+For the full requirements, see [Tier 1 platform policy](platform-tier-policy.md#tier-1-platform-policy) in the Platform Tier Policy.
+
+| platform | os | notes | rust | artifacts
+| -------|-------|-------|-------|-------
+| `x86_64-unknown-linux-gnu` | [Debian 11](https://www.debian.org/releases/bullseye/) | 64-bit | [latest stable release](https://github.com/rust-lang/rust/releases) | Docker
+
+## Tier 2
+
+Tier 2 platforms can be thought of as "guaranteed to build". The Zebra project
+builds in CI for each tier 2 platform, and automated builds ensure that each
+tier 2 platform builds after each change. Not all automated tests are run so it's
+not guaranteed to produce a working build, and official builds are not available,
+but tier 2 platforms often work to quite a good degree and patches are always
+welcome!
+
+For the full requirements, see [Tier 2 platform policy](platform-tier-policy.md#tier-2-platform-policy) in the Platform Tier Policy.
+
+| platform | os | notes | rust | artifacts
+| -------|-------|-------|-------|-------
+| `x86_64-apple-darwin` | [GitHub macos-latest](https://github.com/actions/virtual-environments#available-environments) | 64-bit | [latest stable release](https://github.com/rust-lang/rust/releases) | N/A
+| `x86_64-unknown-linux-gnu` | [GitHub ubuntu-latest](https://github.com/actions/virtual-environments#available-environments) | 64-bit | [latest stable release](https://github.com/rust-lang/rust/releases) | N/A
+| `x86_64-unknown-linux-gnu` | [GitHub ubuntu-latest](https://github.com/actions/virtual-environments#available-environments) | 64-bit | [latest beta release](https://github.com/rust-lang/rust/blob/beta/src/version) | N/A
+
+## Tier 3
+
+Tier 3 platforms are those which the Zebra codebase has support for, but which
+the Zebra project does not build or test automatically, so they may or may not
+work. Official builds are not available.
+
+For the full requirements, see [Tier 3 platform policy](platform-tier-policy.md#tier-3-platform-policy) in the Platform Tier Policy.
+
+| platform | os | notes | rust | artifacts
+| -------|-------|-------|-------|-------
+| `aarch64-unknown-linux-gnu` | [Debian 11](https://www.debian.org/releases/bullseye/) | 64-bit | [latest stable release](https://github.com/rust-lang/rust/releases) | N/A

book/src/user/target-tier-policies.md

@@ -0,0 +1,241 @@
+# Platform Tier Policy
+
+## Table of Contents
+
+- [Platform Tier Policy](#platform-tier-policy)
+  - [Table of Contents](#table-of-contents)
+  - [General](#general)
+  - [Tier 3 platform policy](#tier-3-platform-policy)
+  - [Tier 2 platform policy](#tier-2-platform-policy)
+  - [Tier 1 platform policy](#tier-1-platform-policy)
+
+## General
+
+The Zcash Foundation provides three tiers of platform support, modeled after the
+[Rust Target Tier Policy](https://doc.rust-lang.org/stable/rustc/target-tier-policy.html):
+
+- The Zcash Foundation provides no guarantees about tier 3 platforms; they may
+  or may not build with the actual codebase.
+- Zebra's continuous integration checks that tier 2 platforms will always build,
+  but they may or may not pass tests.
+- Zebra's continuous integration checks that tier 1 platforms will always build
+  and pass tests.
+
+Adding a new tier 3 platform imposes minimal requirements; but we focus
+primarily on avoiding disruption to ongoing Zebra development.
+
+Tier 2 and tier 1 platforms place work on Zcash Foundation developers as a whole,
+to avoid breaking the platform. These tiers require commensurate and ongoing
+efforts from the maintainers of the platform, to demonstrate value and to
+minimize any disruptions to ongoing Zebra development.
+
+This policy defines the requirements for accepting a proposed platform at a
+given level of support.
+
+Each tier is based 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. Targets must fulfill the spirit of the requirements as well, as
+determined by the judgment of the Zebra team.
+
+For a list of all supported platforms and their corresponding tiers ("tier 3",
+"tier 2", or "tier 1"), see
+[platform support](platform-support.md).
+
+Note that a platform must have already received approval for the next lower
+tier, and spent a reasonable amount of time at that tier, before making a
+proposal for promotion to the next higher tier; this is true even if a platform
+meets the requirements for several tiers at once. This policy leaves the
+precise interpretation of "reasonable amount of time" up to the Zebra team.
+
+The availability or tier of a platform in stable Zebra 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
+Zebra team 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, the Zebra project provides no official support for a platform, so
+we place minimal requirements on the introduction of platforms.
+
+- A tier 3 platform must have a designated developer or developers (the "platform
+  maintainers") on record to be CCed when issues arise regarding the platform.
+  (The mechanism to track and CC such developers may evolve over time.)
+- Target names should not introduce undue confusion or ambiguity unless
+  absolutely necessary to maintain ecosystem compatibility. For example, if
+  the name of the platform makes people extremely likely to form incorrect
+  beliefs about what it targets, the name should be changed or augmented to
+  disambiguate it.
+- 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 either the Zebra team of the other tier 3 platform.
+
+If a tier 3 platform stops meeting these requirements, or the platform maintainers
+no longer have interest or time, 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 Zebra codebase, we may post a PR to remove support for that platform. Any such PR will be CCed
+to the platform maintainers (and potentially other people who have previously
+worked on the platform), to check potential interest in improving the situation.
+
+## Tier 2 platform policy
+
+At this tier, the Zebra project guarantees that a platform builds, and will reject
+patches that fail to build on a platform. Thus, we place requirements that ensure
+the platform will not block forward progress of the Zebra project.
+
+A proposed new tier 2 platform must be reviewed and approved by Zebra team based
+on these requirements.
+
+In addition, the devops 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 a devops team member reporting the outcome of a team discussion.
+
+- Tier 2 platforms must implement all the Zcash consensus rules.
+  Other Zebra features and binaries may be disabled, on a case-by-case basis.
+- A tier 2 platform must have a designated team of developers (the "platform
+  maintainers") available to consult on platform-specific build-breaking issues.
+  This team must have at least 1 developer.
+- The platform must not place undue burden on Zebra developers not specifically
+  concerned with that platform. Zebra 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 provide documentation for the Zcash community explaining how
+  to build for their platform, and explaining how to run tests for the platform.
+  If at all possible, this documentation should show how to run Zebra programs
+  and tests for the platform using emulation, to allow anyone to do so. If the
+  platform cannot be feasibly emulated, the documentation should document the
+  required physical hardware or cloud systems.
+- The platform must document its baseline expectations for the features or
+  versions of CPUs, operating systems, and any other dependencies.
+- The platform must build reliably in CI, for all components that Zebra's CI
+  considers mandatory.
+  - Since a working Rust compiler is required to build Zebra,
+    the platform must be a [Rust tier 1 platform](https://rust-lang.github.io/rustup-components-history/).
+- The Zebra team may additionally require that a subset of tests pass in
+  CI. In particular, this requirement may apply if the tests in question provide
+  substantial value via early detection of critical problems.
+- Building the platform in CI must not take substantially longer than the current
+  slowest platform in CI, and should not substantially raise the maintenance
+  burden of the CI infrastructure. This requirement is subjective, to be
+  evaluated by the devops team, and will take the community importance
+  of the platform into account.
+- Test failures on tier 2 platforms will be handled on a case-by-case basis.
+  Depending on the severity of the failure, the Zebra team may decide to:
+  - disable the test on that platform,
+  - require a fix before the next release, or
+  - remove the platform from tier 2.
+- The platform maintainers should regularly run the testsuite for the platform,
+  and should fix any test failures in a reasonably timely fashion.
+- All requirements for tier 3 apply.
+
+A tier 2 platform may be demoted or removed if it no longer meets these
+requirements. Any proposal for demotion or removal will be CCed to the platform
+maintainers, and will be communicated widely to the Zcash community before being
+dropped from a stable release. (The amount of time between such communication
+and the next stable release may depend on the nature and severity of the failed
+requirement, the timing of its discovery, whether the platform has been part of a
+stable release yet, and whether the demotion or removal can be a planned and
+scheduled action.)
+
+## Tier 1 platform policy
+
+At this tier, the Zebra project guarantees that a platform builds and passes all
+tests, and will reject patches that fail to build or pass the testsuite on a
+platform. We hold tier 1 platforms to our highest standard of requirements.
+
+A proposed new tier 1 platform must be reviewed and approved by the Zebra team
+based on these requirements. In addition, the release team must approve the
+viability and value of supporting the platform.
+
+In addition, the devops team must approve the integration of the platform
+into Continuous Integration (CI), and the tier 1 CI-related requirements. This
+review and approval may take place in a PR adding the platform to CI, by a
+devops team member reporting the outcome of a team discussion.
+
+- Tier 1 platforms must implement Zebra's standard production feature set,
+  including the network protocol, mempool, cached state, and RPCs.
+  Exceptions may be made on a case-by-case basis.
+  - Zebra must have reasonable security, performance, and robustness on that platform.
+    These requirements are subjective, and determined by consensus of the Zebra team.
+  - Internal developer tools and manual testing tools may be disabled for that platform.
+- The platform must serve the ongoing needs of multiple production
+  users of Zebra across multiple organizations or projects. These requirements
+  are subjective, and determined by consensus of the Zebra team. 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
+  Zebra's CI considers mandatory.
+  - Test failures on tier 1 platforms will be handled on a case-by-case basis.
+    Depending on the severity of the failure, the Zebra team may decide to:
+    - disable the test on that platform,
+    - require a fix before the next release,
+    - require a fix before any other PRs merge, or
+    - remove the platform from tier 1.
+  - The platform must not disable an excessive number of tests or pieces of tests
+    in the testsuite in order to do so. This is a subjective requirement.
+- Building the platform and running the testsuite for the platform must not take
+  substantially longer than other platforms, and should not substantially raise
+  the maintenance burden of the CI infrastructure.
+  - In particular, if building the platform takes a reasonable amount of time,
+    but the platform cannot run the testsuite in a timely fashion due to low
+    performance, that alone may prevent the platform from qualifying as tier 1.
+- If running the testsuite requires additional infrastructure (such as physical
+  systems running the platform), the platform maintainers must arrange to provide
+  such resources to the Zebra project, to the satisfaction and approval of the
+  Zebra devops team.
+  - Such resources may be provided via cloud systems, via emulation, or via
+    physical hardware.
+  - If the platform requires the use of emulation to meet any of the tier
+    requirements, the Zebra team must have high
+    confidence in the accuracy of the emulation, such that discrepancies
+    between emulation and native operation that affect test results will
+    constitute a high-priority bug in either the emulation, the Rust
+    implementation of the platform, or the Zebra implementation for the platform.
+  - If it is not possible to run the platform via emulation, these resources
+    must additionally be sufficient for the Zebra devops team to make them
+    available for access by Zebra team members, for the purposes of development
+    and testing. (Note that the responsibility for doing platform-specific
+    development to keep the platform well maintained remains with the platform
+    maintainers. This requirement ensures that it is possible for other
+    Zebra developers to test the platform, but does not obligate other Zebra
+    developers to make platform-specific fixes.)
+  - Resources provided for CI and similar infrastructure must be available for
+    continuous exclusive use by the Zebra project. Resources provided
+    for access by Zebra team members for development and testing must be
+    available on an exclusive basis when in use, but need not be available on a
+    continuous basis when not in use.
+- All requirements for tier 2 apply.
+
+A tier 1 platform may be demoted if it no longer meets these requirements but
+still meets the requirements for a lower tier. Any such proposal will be
+communicated widely to the Zcash community, both when initially proposed and
+before being dropped from a stable release. A tier 1 platform is highly unlikely
+to be directly removed without first being demoted to tier 2 or tier 3.
+(The amount of time between such communication and the next stable release may
+depend on the nature and severity of the failed requirement, the timing of its
+discovery, whether the platform has been part of a stable release yet, and
+whether the demotion or removal can be a planned and scheduled action.)
+
+Raising the baseline expectations of a tier 1 platform (such as the minimum CPU
+features or OS version required) requires the approval of the Zebra team, and
+should be widely communicated as well.