Skip to content

Commit 12ce4f7

Browse files
liamaharonkianenigmajuangiriniggwpezcodekitz
authored
Runtime Upgrade ref docs and Single Block Migration example pallet (#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]>
1 parent 7ec0b87 commit 12ce4f7

File tree

87 files changed

+1223
-370
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+1223
-370
lines changed

‎Cargo.lock

Lines changed: 26 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,7 @@ members = [
337337
"substrate/frame/examples/frame-crate",
338338
"substrate/frame/examples/kitchensink",
339339
"substrate/frame/examples/offchain-worker",
340+
"substrate/frame/examples/single-block-migrations",
340341
"substrate/frame/examples/split",
341342
"substrate/frame/examples/tasks",
342343
"substrate/frame/executive",

‎cumulus/pallets/collator-selection/src/lib.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ pub mod pallet {
118118
use sp_staking::SessionIndex;
119119
use sp_std::vec::Vec;
120120

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

124124
type BalanceOf<T> =

‎cumulus/pallets/collator-selection/src/migration.rs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ pub mod v1 {
3131
pub struct MigrateToV1<T>(sp_std::marker::PhantomData<T>);
3232
impl<T: Config> OnRuntimeUpgrade for MigrateToV1<T> {
3333
fn on_runtime_upgrade() -> Weight {
34-
let onchain_version = Pallet::<T>::on_chain_storage_version();
35-
if onchain_version == 0 {
34+
let on_chain_version = Pallet::<T>::on_chain_storage_version();
35+
if on_chain_version == 0 {
3636
let invulnerables_len = Invulnerables::<T>::get().to_vec().len();
3737
<Invulnerables<T>>::mutate(|invulnerables| {
3838
invulnerables.sort();
@@ -45,7 +45,7 @@ pub mod v1 {
4545
invulnerables_len,
4646
);
4747
// Similar complexity to `set_invulnerables` (put storage value)
48-
// Plus 1 read for length, 1 read for `onchain_version`, 1 write to put version
48+
// Plus 1 read for length, 1 read for `on_chain_version`, 1 write to put version
4949
T::WeightInfo::set_invulnerables(invulnerables_len as u32)
5050
.saturating_add(T::DbWeight::get().reads_writes(2, 1))
5151
} else {
@@ -83,8 +83,8 @@ pub mod v1 {
8383
"after migration, there should be the same number of invulnerables"
8484
);
8585

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

8989
Ok(())
9090
}

‎cumulus/pallets/parachain-system/src/migration.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ use frame_support::{
2121
weights::Weight,
2222
};
2323

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

2727
/// Migrates the pallet storage to the most recent version.

‎cumulus/pallets/xcmp-queue/src/migration.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ use frame_support::{
2424
weights::{constants::WEIGHT_REF_TIME_PER_MILLIS, Weight},
2525
};
2626

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

3030
pub const LOG: &str = "runtime::xcmp-queue-migration";

‎cumulus/parachains/pallets/collective-content/src/lib.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ pub mod pallet {
5959
use frame_system::pallet_prelude::*;
6060
use sp_runtime::{traits::BadOrigin, Saturating};
6161

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

6565
#[pallet::pallet]

‎cumulus/parachains/runtimes/assets/asset-hub-rococo/src/lib.rs

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -986,37 +986,37 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
986986
let mut writes = 0;
987987

988988
if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
989-
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
989+
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
990990
writes.saturating_inc();
991991
}
992992

993993
if Multisig::on_chain_storage_version() == StorageVersion::new(0) {
994-
Multisig::current_storage_version().put::<Multisig>();
994+
Multisig::in_code_storage_version().put::<Multisig>();
995995
writes.saturating_inc();
996996
}
997997

998998
if Assets::on_chain_storage_version() == StorageVersion::new(0) {
999-
Assets::current_storage_version().put::<Assets>();
999+
Assets::in_code_storage_version().put::<Assets>();
10001000
writes.saturating_inc();
10011001
}
10021002

10031003
if Uniques::on_chain_storage_version() == StorageVersion::new(0) {
1004-
Uniques::current_storage_version().put::<Uniques>();
1004+
Uniques::in_code_storage_version().put::<Uniques>();
10051005
writes.saturating_inc();
10061006
}
10071007

10081008
if Nfts::on_chain_storage_version() == StorageVersion::new(0) {
1009-
Nfts::current_storage_version().put::<Nfts>();
1009+
Nfts::in_code_storage_version().put::<Nfts>();
10101010
writes.saturating_inc();
10111011
}
10121012

10131013
if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
1014-
ForeignAssets::current_storage_version().put::<ForeignAssets>();
1014+
ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
10151015
writes.saturating_inc();
10161016
}
10171017

10181018
if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
1019-
PoolAssets::current_storage_version().put::<PoolAssets>();
1019+
PoolAssets::in_code_storage_version().put::<PoolAssets>();
10201020
writes.saturating_inc();
10211021
}
10221022

‎cumulus/parachains/runtimes/assets/asset-hub-westend/src/lib.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1037,17 +1037,17 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
10371037
let mut writes = 0;
10381038

10391039
if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
1040-
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
1040+
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
10411041
writes.saturating_inc();
10421042
}
10431043

10441044
if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
1045-
ForeignAssets::current_storage_version().put::<ForeignAssets>();
1045+
ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
10461046
writes.saturating_inc();
10471047
}
10481048

10491049
if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
1050-
PoolAssets::current_storage_version().put::<PoolAssets>();
1050+
PoolAssets::in_code_storage_version().put::<PoolAssets>();
10511051
writes.saturating_inc();
10521052
}
10531053

‎cumulus/parachains/runtimes/bridge-hubs/bridge-hub-rococo/src/lib.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -168,12 +168,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
168168
let mut writes = 0;
169169

170170
if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
171-
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
171+
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
172172
writes.saturating_inc();
173173
}
174174

175175
if Balances::on_chain_storage_version() == StorageVersion::new(0) {
176-
Balances::current_storage_version().put::<Balances>();
176+
Balances::in_code_storage_version().put::<Balances>();
177177
writes.saturating_inc();
178178
}
179179

‎cumulus/parachains/runtimes/bridge-hubs/bridge-hub-westend/src/lib.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,12 +142,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
142142
let mut writes = 0;
143143

144144
if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
145-
PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
145+
PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
146146
writes.saturating_inc();
147147
}
148148

149149
if Balances::on_chain_storage_version() == StorageVersion::new(0) {
150-
Balances::current_storage_version().put::<Balances>();
150+
Balances::in_code_storage_version().put::<Balances>();
151151
writes.saturating_inc();
152152
}
153153

‎docs/sdk/Cargo.toml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ node-cli = { package = "staging-node-cli", path = "../../substrate/bin/node/cli"
3333
kitchensink-runtime = { path = "../../substrate/bin/node/runtime" }
3434
chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../substrate/bin/utils/chain-spec-builder" }
3535
subkey = { path = "../../substrate/bin/utils/subkey" }
36+
frame-system = { path = "../../substrate/frame/system", default-features = false }
37+
frame-support = { path = "../../substrate/frame/support", default-features = false }
38+
frame-executive = { path = "../../substrate/frame/executive", default-features = false }
39+
pallet-example-single-block-migrations = { path = "../../substrate/frame/examples/single-block-migrations" }
3640

3741
# Substrate
3842
sc-network = { path = "../../substrate/client/network" }
@@ -66,14 +70,15 @@ pallet-proxy = { path = "../../substrate/frame/proxy" }
6670
pallet-authorship = { path = "../../substrate/frame/authorship" }
6771
pallet-collective = { path = "../../substrate/frame/collective" }
6872
pallet-democracy = { path = "../../substrate/frame/democracy" }
69-
frame-system = { path = "../../substrate/frame/system" }
73+
pallet-scheduler = { path = "../../substrate/frame/scheduler" }
7074

7175
# Primitives
7276
sp-io = { path = "../../substrate/primitives/io" }
7377
sp-api = { path = "../../substrate/primitives/api" }
7478
sp-core = { path = "../../substrate/primitives/core" }
7579
sp-keyring = { path = "../../substrate/primitives/keyring" }
7680
sp-runtime = { path = "../../substrate/primitives/runtime" }
81+
sp-version = { path = "../../substrate/primitives/version" }
7782

7883
# XCM
7984
xcm = { package = "staging-xcm", path = "../../polkadot/xcm" }

‎docs/sdk/src/reference_docs/frame_runtime_migration.rs

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)