Skip to content

Commit

Permalink
Runtime Upgrade ref docs and Single Block Migration example pallet (#…
Browse files Browse the repository at this point in the history
…1554)

Closes paritytech/polkadot-sdk-docs#55

- Changes 'current storage version' terminology to less ambiguous
'in-code storage version' (suggestion by @ggwpez)
- Adds a new example pallet `pallet-example-single-block-migrations`
- Adds a new reference doc to replace
https://docs.substrate.io/maintain/runtime-upgrades/ (temporarily living
in the pallet while we wait for developer hub PR to merge)
- Adds documentation for the `storage_alias` macro
- Improves `trait Hooks` docs 
- Improves `trait GetStorageVersion` docs
- Update the suggested patterns for using `VersionedMigration`, so that
version unchecked migrations are never exported
- Prevents accidental usage of version unchecked migrations in runtimes

paritytech/substrate#14421 (comment)
- Unversioned migration code is kept inside `mod version_unchecked`,
versioned code is kept in `pub mod versioned`
- It is necessary to use modules to limit visibility because the inner
migration must be `pub`. See
rust-lang/rust#30905 and

https://internals.rust-lang.org/t/lang-team-minutes-private-in-public-rules/4504/40
for more.

### todo

- [x] move to reference docs to proper place within sdk-docs (now that
#2102 is merged)
- [x] prdoc

---------

Co-authored-by: Kian Paimani <[email protected]>
Co-authored-by: Juan <[email protected]>
Co-authored-by: Oliver Tale-Yazdi <[email protected]>
Co-authored-by: command-bot <>
Co-authored-by: gupnik <[email protected]>
  • Loading branch information
5 people authored Feb 28, 2024
1 parent 7ec0b87 commit 12ce4f7
Show file tree
Hide file tree
Showing 87 changed files with 1,223 additions and 370 deletions.
26 changes: 26 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,7 @@ members = [
"substrate/frame/examples/frame-crate",
"substrate/frame/examples/kitchensink",
"substrate/frame/examples/offchain-worker",
"substrate/frame/examples/single-block-migrations",
"substrate/frame/examples/split",
"substrate/frame/examples/tasks",
"substrate/frame/executive",
Expand Down
2 changes: 1 addition & 1 deletion cumulus/pallets/collator-selection/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ pub mod pallet {
use sp_staking::SessionIndex;
use sp_std::vec::Vec;

/// The current storage version.
/// The in-code storage version.
const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);

type BalanceOf<T> =
Expand Down
10 changes: 5 additions & 5 deletions cumulus/pallets/collator-selection/src/migration.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ pub mod v1 {
pub struct MigrateToV1<T>(sp_std::marker::PhantomData<T>);
impl<T: Config> OnRuntimeUpgrade for MigrateToV1<T> {
fn on_runtime_upgrade() -> Weight {
let onchain_version = Pallet::<T>::on_chain_storage_version();
if onchain_version == 0 {
let on_chain_version = Pallet::<T>::on_chain_storage_version();
if on_chain_version == 0 {
let invulnerables_len = Invulnerables::<T>::get().to_vec().len();
<Invulnerables<T>>::mutate(|invulnerables| {
invulnerables.sort();
Expand All @@ -45,7 +45,7 @@ pub mod v1 {
invulnerables_len,
);
// Similar complexity to `set_invulnerables` (put storage value)
// Plus 1 read for length, 1 read for `onchain_version`, 1 write to put version
// Plus 1 read for length, 1 read for `on_chain_version`, 1 write to put version
T::WeightInfo::set_invulnerables(invulnerables_len as u32)
.saturating_add(T::DbWeight::get().reads_writes(2, 1))
} else {
Expand Down Expand Up @@ -83,8 +83,8 @@ pub mod v1 {
"after migration, there should be the same number of invulnerables"
);

let onchain_version = Pallet::<T>::on_chain_storage_version();
frame_support::ensure!(onchain_version >= 1, "must_upgrade");
let on_chain_version = Pallet::<T>::on_chain_storage_version();
frame_support::ensure!(on_chain_version >= 1, "must_upgrade");

Ok(())
}
Expand Down
2 changes: 1 addition & 1 deletion cumulus/pallets/parachain-system/src/migration.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ use frame_support::{
weights::Weight,
};

/// The current storage version.
/// The in-code storage version.
pub const STORAGE_VERSION: StorageVersion = StorageVersion::new(2);

/// Migrates the pallet storage to the most recent version.
Expand Down
2 changes: 1 addition & 1 deletion cumulus/pallets/xcmp-queue/src/migration.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ use frame_support::{
weights::{constants::WEIGHT_REF_TIME_PER_MILLIS, Weight},
};

/// The current storage version.
/// The in-code storage version.
pub const STORAGE_VERSION: StorageVersion = StorageVersion::new(4);

pub const LOG: &str = "runtime::xcmp-queue-migration";
Expand Down
2 changes: 1 addition & 1 deletion cumulus/parachains/pallets/collective-content/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ pub mod pallet {
use frame_system::pallet_prelude::*;
use sp_runtime::{traits::BadOrigin, Saturating};

/// The current storage version.
/// The in-code storage version.
const STORAGE_VERSION: StorageVersion = StorageVersion::new(0);

#[pallet::pallet]
Expand Down
14 changes: 7 additions & 7 deletions cumulus/parachains/runtimes/assets/asset-hub-rococo/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -986,37 +986,37 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
let mut writes = 0;

if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
writes.saturating_inc();
}

if Multisig::on_chain_storage_version() == StorageVersion::new(0) {
Multisig::current_storage_version().put::<Multisig>();
Multisig::in_code_storage_version().put::<Multisig>();
writes.saturating_inc();
}

if Assets::on_chain_storage_version() == StorageVersion::new(0) {
Assets::current_storage_version().put::<Assets>();
Assets::in_code_storage_version().put::<Assets>();
writes.saturating_inc();
}

if Uniques::on_chain_storage_version() == StorageVersion::new(0) {
Uniques::current_storage_version().put::<Uniques>();
Uniques::in_code_storage_version().put::<Uniques>();
writes.saturating_inc();
}

if Nfts::on_chain_storage_version() == StorageVersion::new(0) {
Nfts::current_storage_version().put::<Nfts>();
Nfts::in_code_storage_version().put::<Nfts>();
writes.saturating_inc();
}

if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
ForeignAssets::current_storage_version().put::<ForeignAssets>();
ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
writes.saturating_inc();
}

if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
PoolAssets::current_storage_version().put::<PoolAssets>();
PoolAssets::in_code_storage_version().put::<PoolAssets>();
writes.saturating_inc();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1037,17 +1037,17 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
let mut writes = 0;

if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
writes.saturating_inc();
}

if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
ForeignAssets::current_storage_version().put::<ForeignAssets>();
ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
writes.saturating_inc();
}

if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
PoolAssets::current_storage_version().put::<PoolAssets>();
PoolAssets::in_code_storage_version().put::<PoolAssets>();
writes.saturating_inc();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -168,12 +168,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
let mut writes = 0;

if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
writes.saturating_inc();
}

if Balances::on_chain_storage_version() == StorageVersion::new(0) {
Balances::current_storage_version().put::<Balances>();
Balances::in_code_storage_version().put::<Balances>();
writes.saturating_inc();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -142,12 +142,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
let mut writes = 0;

if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
writes.saturating_inc();
}

if Balances::on_chain_storage_version() == StorageVersion::new(0) {
Balances::current_storage_version().put::<Balances>();
Balances::in_code_storage_version().put::<Balances>();
writes.saturating_inc();
}

Expand Down
7 changes: 6 additions & 1 deletion docs/sdk/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ node-cli = { package = "staging-node-cli", path = "../../substrate/bin/node/cli"
kitchensink-runtime = { path = "../../substrate/bin/node/runtime" }
chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../substrate/bin/utils/chain-spec-builder" }
subkey = { path = "../../substrate/bin/utils/subkey" }
frame-system = { path = "../../substrate/frame/system", default-features = false }
frame-support = { path = "../../substrate/frame/support", default-features = false }
frame-executive = { path = "../../substrate/frame/executive", default-features = false }
pallet-example-single-block-migrations = { path = "../../substrate/frame/examples/single-block-migrations" }

# Substrate
sc-network = { path = "../../substrate/client/network" }
Expand Down Expand Up @@ -66,14 +70,15 @@ pallet-proxy = { path = "../../substrate/frame/proxy" }
pallet-authorship = { path = "../../substrate/frame/authorship" }
pallet-collective = { path = "../../substrate/frame/collective" }
pallet-democracy = { path = "../../substrate/frame/democracy" }
frame-system = { path = "../../substrate/frame/system" }
pallet-scheduler = { path = "../../substrate/frame/scheduler" }

# Primitives
sp-io = { path = "../../substrate/primitives/io" }
sp-api = { path = "../../substrate/primitives/api" }
sp-core = { path = "../../substrate/primitives/core" }
sp-keyring = { path = "../../substrate/primitives/keyring" }
sp-runtime = { path = "../../substrate/primitives/runtime" }
sp-version = { path = "../../substrate/primitives/version" }

# XCM
xcm = { package = "staging-xcm", path = "../../polkadot/xcm" }
Expand Down
9 changes: 0 additions & 9 deletions docs/sdk/src/reference_docs/frame_runtime_migration.rs

This file was deleted.

Loading

0 comments on commit 12ce4f7

Please sign in to comment.