Runtime Upgrade ref docs and Single Block Migration example pallet (#1554)

Closes https://github.com/paritytech/polkadot-sdk-docs/issues/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

https://github.com/paritytech/substrate/pull/14421#discussion_r1255467895
- 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
https://github.com/rust-lang/rust/issues/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
https://github.com/paritytech/polkadot-sdk/pull/2102 is merged)
- [x] prdoc

---------

Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Juan <juangirini@gmail.com>
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
Co-authored-by: command-bot <>
Co-authored-by: gupnik <nikhilgupta.iitk@gmail.com>

substrate/frame/support/test/tests/construct_runtime.rs

@@ -683,7 +683,7 @@ fn test_metadata() {
 					name: "Version",
 					ty: meta_type::<RuntimeVersion>(),
 					value: RuntimeVersion::default().encode(),
-					docs: maybe_docs(vec![ " Get the chain's current version."]),
+					docs: maybe_docs(vec![ " Get the chain's in-code version."]),
 				},
 				PalletConstantMetadata {
 					name: "SS58Prefix",

substrate/frame/support/test/tests/pallet.rs

@@ -590,7 +590,7 @@ pub mod pallet2 {
 			Self::deposit_event(Event::Something(31));
 
 			if UpdateStorageVersion::get() {
-				Self::current_storage_version().put::<Self>();
+				Self::in_code_storage_version().put::<Self>();
 			}
 
 			Weight::zero()
@@ -1310,7 +1310,7 @@ fn pallet_on_genesis() {
 		assert_eq!(pallet::Pallet::<Runtime>::on_chain_storage_version(), StorageVersion::new(0));
 		pallet::Pallet::<Runtime>::on_genesis();
 		assert_eq!(
-			pallet::Pallet::<Runtime>::current_storage_version(),
+			pallet::Pallet::<Runtime>::in_code_storage_version(),
 			pallet::Pallet::<Runtime>::on_chain_storage_version(),
 		);
 	})
@@ -2257,10 +2257,10 @@ fn pallet_on_chain_storage_version_initializes_correctly() {
 		AllPalletsWithSystem,
 	>;
 
-	// Simple example of a pallet with current version 10 being added to the runtime for the first
+	// Simple example of a pallet with in-code version 10 being added to the runtime for the first
 	// time.
 	TestExternalities::default().execute_with(|| {
-		let current_version = Example::current_storage_version();
+		let in_code_version = Example::in_code_storage_version();
 
 		// Check the pallet has no storage items set.
 		let pallet_hashed_prefix = twox_128(Example::name().as_bytes());
@@ -2271,14 +2271,14 @@ fn pallet_on_chain_storage_version_initializes_correctly() {
 		// version.
 		Executive::execute_on_runtime_upgrade();
 
-		// Check that the storage version was initialized to the current version
+		// Check that the storage version was initialized to the in-code version
 		let on_chain_version_after = StorageVersion::get::<Example>();
-		assert_eq!(on_chain_version_after, current_version);
+		assert_eq!(on_chain_version_after, in_code_version);
 	});
 
-	// Pallet with no current storage version should have the on-chain version initialized to 0.
+	// Pallet with no in-code storage version should have the on-chain version initialized to 0.
 	TestExternalities::default().execute_with(|| {
-		// Example4 current_storage_version is NoStorageVersionSet.
+		// Example4 in_code_storage_version is NoStorageVersionSet.
 
 		// Check the pallet has no storage items set.
 		let pallet_hashed_prefix = twox_128(Example4::name().as_bytes());
@@ -2308,7 +2308,7 @@ fn post_runtime_upgrade_detects_storage_version_issues() {
 
 	impl OnRuntimeUpgrade for CustomUpgrade {
 		fn on_runtime_upgrade() -> Weight {
-			Example2::current_storage_version().put::<Example2>();
+			Example2::in_code_storage_version().put::<Example2>();
 
 			Default::default()
 		}
@@ -2351,14 +2351,14 @@ fn post_runtime_upgrade_detects_storage_version_issues() {
 	>;
 
 	TestExternalities::default().execute_with(|| {
-		// Set the on-chain version to one less than the current version for `Example`, simulating a
+		// Set the on-chain version to one less than the in-code version for `Example`, simulating a
 		// forgotten migration
 		StorageVersion::new(9).put::<Example2>();
 
 		// The version isn't changed, we should detect it.
 		assert!(
 			Executive::try_runtime_upgrade(UpgradeCheckSelect::PreAndPost).unwrap_err() ==
-				"On chain and current storage version do not match. Missing runtime upgrade?"
+				"On chain and in-code storage version do not match. Missing runtime upgrade?"
 					.into()
 		);
 	});

substrate/frame/support/test/tests/pallet_ui/compare_unset_storage_version.rs

@@ -29,7 +29,7 @@ mod pallet {
 	#[pallet::hooks]
 	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
 		fn on_runtime_upgrade() -> Weight {
-			if Self::current_storage_version() != Self::on_chain_storage_version() {
+			if Self::in_code_storage_version() != Self::on_chain_storage_version() {
 
 			}
 

substrate/frame/support/test/tests/pallet_ui/compare_unset_storage_version.stderr

@@ -1,7 +1,7 @@
 error[E0369]: binary operation `!=` cannot be applied to type `NoStorageVersionSet`
   --> tests/pallet_ui/compare_unset_storage_version.rs:32:39
    |
-32 |             if Self::current_storage_version() != Self::on_chain_storage_version() {
+32 |             if Self::in_code_storage_version() != Self::on_chain_storage_version() {
    |                ------------------------------- ^^ -------------------------------- StorageVersion
    |                |
    |                NoStorageVersionSet