Skip to content
Snippets Groups Projects
Select Git revision
0 results
Blame History Permalink
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
RELEASE.md 7.77 KiB

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 or experimental 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

  1. Developer opens a Pull Request with changed crates against master.
  2. 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.