book: Add platform support information and tier policy
This commit is contained in:
Jack Grigg
parent
aeea89f704
commit
9f6b7ab85a
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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 |
|
||||
Loading…
Reference in New Issue