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]>

Cargo.toml

@@ -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",

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

@@ -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> =

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

@@ -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();
@@ -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 {
@@ -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(())
 		}

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

@@ -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.

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

@@ -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";

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

@@ -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]

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

@@ -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();
 		}
 

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

@@ -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();
 		}
 

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

@@ -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();
 		}
 

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

@@ -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();
 		}
 

docs/sdk/Cargo.toml

@@ -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" }
@@ -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" }