Step by Step Upgrade Workflow

Step 1 – Establish Baseline

• Confirm current runtime version via Polkadot JS Apps or by querying the chain.

• Document the current spec_version, pallet versions, and critical dependencies.

Step 2 – Select Target Version

• Identify the next stable Polkadot SDK release.

• For Paseo, check the network forum or Polkadot governance announcements to ensure compatibility.

Step 3 – Bump Dependencies

• Run:

  psvm -v stableYYMM-ZZ

• Run zepter fix to resolve formatting, deprecated flags, or unused imports introduced by the bump.

Step 4 – Review Changes

• Study changelogs for:

  • Node-level changes (networking, storage backend, consensus).

  • Runtime changes (new pallets, storage migrations, updated APIs).

• Compare your runtime against Polkadot SDK templates or reference repos (e.g., base-parachain).

Step 5 – Update Runtime Metadata

• In runtime/src/lib.rs:

  • Increment spec_version.

• In Cargo.toml:

  • Increment runtime package version.

Step 6 – Handle Migrations

• If storage structures or APIs changed:

  • Implement migration logic in your runtime.

  • Test migrations locally using try-runtime.

Step 7 – Build and Test

• Build artifacts:

  cargo build --release

• Verify the WASM runtime is correctly generated.

• Run unit tests and integration tests.

Step 8 – Deploy Runtime Upgrade

• Development / testnet: via Sudo extrinsic in Polkadot.js Apps.

• Mainnet: through governance-approved proposals.

Step 9 – Verify Upgrade

• Confirm on-chain that the runtime version reflects the bump.

• Run end-to-end functional tests against your chain.