242 lines
14 KiB
Markdown
242 lines
14 KiB
Markdown
# 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.
|