zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Gustavo Valverde 2022-07-22 12:23:10 -04:00 committed by GitHub
parent 6ad445eb97
commit 4257f60265
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 294 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
book/src/user/requirements.md
View File

@ -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)

49
book/src/user/supported-platforms.md Normal file
View File

@ -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

241
book/src/user/target-tier-policies.md Normal file
View File

@ -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.