mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-09 20:11:09 +00:00
Release Process (#2490)
Writing down the processes to do our releases. Status: please review & approve so we can go ahead. --------- Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com> Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> Co-authored-by: Bastian Köcher <git@kchr.de> Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Co-authored-by: Jegor Sidorenko <5252494+jsidorenko@users.noreply.github.com>
This commit is contained in:
Oliver Tale-Yazdi
committed by
GitHub
GitHub
parent
3717ec3802
commit
d72fb58070
@@ -35,6 +35,26 @@ Polkadot.
|
||||
|
||||
Cumulus is a set of tools for writing Substrate-based Polkadot parachains.
|
||||
|
||||
## Releases
|
||||
|
||||
> [!NOTE]
|
||||
> Our release process is still Work-In-Progress and may not yet reflect the aspired outline here.
|
||||
|
||||
The Polkadot-SDK has two release channels: `stable` and `nightly`. Production software is advised to only use `stable`.
|
||||
`nightly` is meant for tinkerers to try out the latest features. The detailed release process is described in
|
||||
[RELEASE.md](docs/RELEASE.md).
|
||||
|
||||
### Stable
|
||||
|
||||
`stable` releases have a support duration of **three months**. In this period, the release will not have any breaking
|
||||
changes. It will receive bug fixes, security fixes, performance fixes and new non-breaking features on a **two week**
|
||||
cadence.
|
||||
|
||||
### Nightly
|
||||
|
||||
`nightly` releases are released every night from the `master` branch, potentially with breaking changes. They have
|
||||
pre-release version numbers in the format `major.0.0-nightlyYYMMDD`.
|
||||
|
||||
## Upstream Dependencies
|
||||
|
||||
Below are the primary upstream dependencies utilized in this project:
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# Audit
|
||||
|
||||
Audits are conducted to ensure the absence of severe or exploitable bugs. Pull Requests are generally merged into the
|
||||
`master` branch without audit. The `audited` tag is used to track the latest audited commit of the `master` branch. This
|
||||
means that audits need to happen in order of being merged.
|
||||
This is an optimistic approach that lets us develop with greater speed, while requiring (possibly) large refactors in
|
||||
the failure case.
|
||||
|
||||
Audits can be deferred if the logic is gated by an `experimental` feature or marked as "Not Production Ready" within the
|
||||
first line of doc. Such changes should be queued manually before these warnings are removed.
|
||||
|
||||
## General Guidelines for what to Audit
|
||||
|
||||
There is no single one-fits-all rule. Generally we should audit important logic that could immediately be used on
|
||||
production networks. If in doubt, ask in chat or in the Merge Request.
|
||||
|
||||
## Requesting an Audit
|
||||
|
||||
1. Add the PR to the project `Security Audit (PRs) - SRLabs`
|
||||
2. Set status to Backlog
|
||||
3. Assign priority, considering the universe of PRs currently in the backlog
|
||||
4. Add the component
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
# 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](#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](https://semver.org/) as best as possible for versioning our crates. 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`](https://paritytech.github.io/polkadot-sdk/master/polkadot_node_primitives/constant.NODE_VERSION.html)
|
||||
variable.
|
||||
|
||||
## Westend & Rococo
|
||||
|
||||
For the 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](#bug-and-security-fix) 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](#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](https://doc.rust-lang.org/cargo/reference/semver.html) 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`](https://github.com/obi1kenobi/cargo-semver-checks).
|
||||
|
||||
### Steps
|
||||
|
||||
1. Developer opens a Pull Request with changed crates against `master`.
|
||||
1. 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.
|
||||
|
||||
This process aims to release the `stable` branch as a *Stable* release every two weeks.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Check and execute process [Clobbering](#clobbering), if needed.
|
||||
2. Check if there were any changes since the last release and abort, if not.
|
||||
3. Check out the latest commit of `stable`.
|
||||
4. Update the `CHANGELOG.md` version, date and compile the content using the PrDoc files.
|
||||
5. Open a Pull Request against `stable` for visibility of the release happening.
|
||||
6. Internal QA from the release team can happen here.
|
||||
7. Do a dry-run release to ensure that it *should* work.
|
||||
8. Comment in the Pull Request that a *Stable* release will happen from the merged commit hash.
|
||||
9. Release all changed crates to crates.io.
|
||||
10. Create the release `stableYYYYMMDD` on GitHub. Note that the Fellowship has a streamlined process that combines the
|
||||
two last steps. A similar approach should be taken here.
|
||||
|
||||
## Nightly Release
|
||||
|
||||
Cadence: every day at 00:00 UTC+1. Responsible: Release Team
|
||||
|
||||
This process aims to release the `master` branch as a *Nightly* release. The process can start at 00:00 UTC+1 and should
|
||||
automatically do the following steps.
|
||||
|
||||
1. Check out the latest commit of branch `master`.
|
||||
2. Compare this commit to the latest `nightly*` tag and abort if there are no changes detected.
|
||||
3. Set the version of all crates that changed to `major.0.0-nightlyYYMMDD` where `major` is the last released `major`
|
||||
version of that crate plus one.
|
||||
4. Patch the dependencies of the changed crates to point to the newest version of the dependency.
|
||||
5. Tag this commit as `nightlyYYMMDD`.
|
||||
6. Do a dry-run release to ensure that it *should* work.
|
||||
7. Push this tag (the commit will not belong to any branch).
|
||||
8. Release all crates that had changed to crates.io.
|
||||
|
||||
## Clobbering
|
||||
|
||||
Cadence: every 6th release (~3 months). Responsible: Release Team
|
||||
|
||||
This process aims to bring branch `stable` in sync with the latest audited commit of `master`. It is not done via a Pull
|
||||
Request but rather by just copying files. It should be automated.
|
||||
The following script is provided to do the clobbering. Note that it keeps the complete history of all past clobbering
|
||||
processes.
|
||||
|
||||
```bash
|
||||
# Ensure we have the latest remote data
|
||||
git fetch
|
||||
# Switch to the stable branch
|
||||
git checkout stable
|
||||
|
||||
# Delete all tracked files in the working directory
|
||||
git ls-files -z | xargs -0 rm -f
|
||||
# Find and delete any empty directories
|
||||
find . -type d -empty -delete
|
||||
|
||||
# Get the last audited commit
|
||||
AUDITED=$(git rev-parse --short=10 origin/audited)
|
||||
# Grab the files from the commit
|
||||
git checkout $AUDITED -- .
|
||||
|
||||
# Stage, commit, and push the working directory which now matches 'audited' 1:1
|
||||
git add .
|
||||
git commit -m "Clobbering with audited ($AUDITED)"
|
||||
git push
|
||||
```
|
||||
|
||||
## Bug and Security Fix
|
||||
|
||||
Cadence: n.a. Responsible: Developer
|
||||
|
||||
Describes how developers should merge bug and security fixes.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Developer opens a Pull Request with a bug or security fix.
|
||||
2. The Pull Request is marked as priority fix.
|
||||
3. Audit happens with priority.
|
||||
4. It is merged into `master`.
|
||||
5. It is automatically back-ported to `stable`.
|
||||
6. The fix will be released in the next *Stable* release. In urgent cases, a release can happen earlier.
|
||||
Reference in New Issue
Block a user