Skip to content

Upgrading to a new Polkadot Release

Jump to bottom
eNddy edited this page Sep 4, 2024 · 9 revisions

Polkadot-sdk Upgrade

Step by Step guide.

  1. Search and replace the old version with the new version. For example: “0.9.39” with “0.9.40”. This tool is available to automate this task: https://github.com/paritytech/diener Try to upgrade one release at a time, as it is easier to track down the changes that may have caused problems. However, if the release notes, or code changes suggest changes in a further release are related to any difficult issues encountered during an upgrade, it may be worth exploring moving to the next release to see if those issues are resolved. For example, this was the situation when upgrading to v0.9.40. An error could not be resolved, but was solved when moving to v0.9.42.

  2. Check the dependencies in the various Cargo.toml files and update them. Specifically, the non-Substrate crates, use the same version that Parity is using for the polkadot version. For example:

    codec = { package = "parity-scale-codec", version = "3.2.2", default-features = false, features = [
"derive",

  3. Update other, non-polkadot-sdk dependencies to the latest versions as needed.

  • cargo tree -d can be used to show duplicates (although polkadot-sdk creates a lot of noise).
  • cargo tree -i can be used to find where a package is included from.
  • cargo udeps can be used to show unused dependencies. Be careful, as only one feature can be specified at one time, this tool may show false positives. Be sure to cross-reference against all the valid features, e.g. frequency,frequency-no-relay,frequency-local,frequency-testnet.
  • Here are some packages that should be checked for updates in polkadot-sdk: scale-info, parity-scale-codec, smallvec, serde, serde_json, tokio.
  • Run cargo update and add the Cargo.lock file to your commit.
  1. Run make check and start fixing compile errors.
  2. Reference the Polkadot release notes, e.g. https://github.com/paritytech/polkadot/releases/tag/v0.9.40 and the release analysis, e.g. Polkadot Release Analysis v1.1.0
  3. Further, reference the substrate or cumulus pull request to fix the compile errors. For example: https://github.com/paritytech/substrate/pull/12828 and https://github.com/paritytech/cumulus/pull/1939. These two links provide examples of the changes that caused an error when upgrading from v0.9.39 to v0.9.40. These PR's were referenced in the release notes or the release analysis.
  4. Group changes based on errors and commit them to your branch. Use https://www.conventionalcommits.org/en/v1.0.0/ to label your commits. For example: build: update to polkadot 0.9.40 or fix: substrate issue(13535): Remove use of trait Store
  5. When make check passes, test with make ci-local. make ci-local executes make lint, make test, and make e2e-tests. If make ci-local errors, run the individual make commands and determine what caused the errors.
  6. Further testing should be done using make upgrade-local and make upgrade-no-relay to make sure that runtime upgrades are successful and will be successful moving forward.
  7. Update the polkadot version used in the testing scripts to setup up development environments. For example, look here: resources/rococo-local.json and scripts/generate_relay_specs.sh as was done in PR #1808.
  8. Rust Toolchain. The polkadot-sdk release notes will report which versions of Rust are compatible with this release. If the stable or nightly versions need to be updated, then ci-base-image should be updated with the new versions.
  1. Upgrade Polkadot Docker Image to match SDK version.
Clone this wiki locally