TLDR; Pull Requests will be required to provide SemVer bumps for all modified crates.
As first step towards the overall “Stabilizing Polkadot” goal, we will add SemVer information to all changes in the Polkadot-SDK. A CI check that scans all modified crates of a Pull Request is currently being added. This check ensures that all changes to crates are classified as either patch, minor or major.
SemVer… what?
SemVer, short for Semantic Versioning, is a standard to classify changes to source code. It is the default in the Rust ecosystem, and assumed by many Rust-specific tools. Polkadot-SDK not adopting this so far has lead to great headdache and frustation among its users.
A more in-depth explanation for each category is in our RELEASE.md, and on rust-lang.org.
Why?
Introducing SemVer will allow downstream teams to integrate changes more selectively. Currently, they are forced to do an all-or-nothing upgrade of their code when Polkadot-SDK does some change. The envisioned goal here is to minimize downstream pain, while not losing rollout velocity for critical changes.
Ultimately, this will reduce costs of maintaining production software with Polkadot-SDK.
How?
We make use of prdoc to inform downstream devs about semantical changes to our code. Now we will extend the format of these prdoc files to include a bump field for every modified crate.
Concretely, the green lines are new:
crates:
- name: frame-support
+ bump: major
- name: frame-system
+ bump: minor
They need to be filled in by the developer who does the changes. There is currently no conveinence tooling to help with this, but we will add some CLI to help with listing all modified crates (and possibly pre-filling some things).
CI
The CI only acts as sanity check. Devs still need to ensure correctness to avoid breaking downstream code!
This is the output of the CI in this case that three crates have no/incorrect SemVer information their prdoc file:
There is an escape-hatch for the possibility that we have a corner-case in the CI that it detects incorrectly. For example, when the CI detects a major change, but the dev is 100% sure that it is actually minor, then the check can be skipped with validate: false:
- name: frame-support
patch: minor
+ validate: false
WHEN?
Target for the New Release Process is end of Q2. The SemVer check will be added sooner™️, latest by mid May. But this check itself is just one piece of the whole process.
The announcement here is mostly for Devs to not be surprised when they see the CI failing.