-
omahs authored
chore: fix typos
Unverified89b67bc6
Release
The outputs of a release are the polkadot
and polkadot-parachain
node binaries, the runtimes for Westend & Rococo
and their system parachains, and new crate versions published to crates.io
.
Setup
We have two branches: master
and stable
. master
is the main development branch where normal Pull Requests are
opened. Developers need to mostly only care about this branch.
The stable
branch contains a version of the code that is ready to be released. Its contents are always audited.
Merging to it is restricted to Backports.
Versioning
We are releasing multiple different things from this repository in one release, but we don't want to use the same
version for everything. Thus, in the following we explain the versioning story for the crates, node and Westend &
Rococo. To easily refer to a release, it shall be named by its date in the form stableYYMMDD
.
Crate
We try to follow SemVer 2.0.0 as best as possible for versioning our crates. The definitions of
major
, minor
and patch
version for Rust crates are slightly altered from their standard for pre 1.0.0
versions.
Quoting rust-lang.org:
Initial development releases starting with “0.y.z” can treat changes in “y” as a major release, and “z” as a minor release. “0.0.z” releases are always major changes. This is because Cargo uses the convention that only changes in the left-most non-zero component are considered incompatible.
SemVer requires a piece of software to first declare a public API. The public API of the Polkadot SDK is hereby declared as the sum of all crates' public APIs.
Inductively, the public API of our library crates is declared as all public items that are neither:
- Inside a
__private
module - Documented as "unstable" or "experimental" in the first line of docs
- Bear
unstable
orexperimental
in their absolute path
Node
The versioning of the Polkadot node is done most of the time by only incrementing the minor
version. The major
version is only bumped for special releases and the patch
can be used for an out of band release that fixes some
critical bug. The node version is not following SemVer. This means that the version doesn't express if there are any
breaking changes in the CLI interface or similar. The node version is declared in the
NODE_VERSION
variable.
Westend & Rococo
For these networks, in addition to incrementing the Cargo.toml
version we also increment the spec_version
and
sometimes the transaction_version
. The spec version is also following the node version. Its schema is: M_mmm_ppp
and
for example 1_002_000
is the node release 1.2.0
. This versioning has no further meaning, and is only done to map
from an on chain spec_version
easily to the release in this repository.
The Westend testnet will be updated to a new runtime every two weeks with the latest nightly
release.
Backports
From master
to stable
Backports in this direction can be anything that is audited and either a minor
or a patch
bump. Security
fixes should be prioritized over additions or improvements. Crates that are declared as internal
API can also have major
version bumps through backports.
From stable
to master
Should not be needed since all changes first get merged into master
. The stable
branch can get out of sync and will
be synced with the Clobbering process.
Processes
The following processes are necessary to actualize our releases. Each process has a Cadence on which it must execute and a Responsible that is responsible for autonomously doing so and reporting back any error in the RelEng: Polkadot Release Coordination Matrix channel. All processes should be automated as much as possible.
Crate Bumping
Cadence: (possibly) each Pull Request. Responsible: Developer that opened the Pull Request.
Following SemVer isn't easy, but there exists a guide in the
Rust documentation that explains the small details on when to bump what. This process is supported with a CI check that
utilizes cargo-semver-checks
.
Steps
- Developer opens a Pull Request with changed crates against
master
. - They bump all changed crates according to SemVer. Note that this includes any crates that expose the changed behaviour in their public API and also transitive dependencies for whom the same rule applies.
Stable Release
Cadence: every two weeks. Responsible: Release Team.