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>

polkadot/runtime/common/src/assigned_slots/migration.rs

@@ -29,14 +29,14 @@ pub mod v1 {
 	impl<T: Config> OnRuntimeUpgrade for VersionUncheckedMigrateToV1<T> {
 		#[cfg(feature = "try-runtime")]
 		fn pre_upgrade() -> Result<Vec<u8>, sp_runtime::TryRuntimeError> {
-			let onchain_version = Pallet::<T>::on_chain_storage_version();
-			ensure!(onchain_version < 1, "assigned_slots::MigrateToV1 migration can be deleted");
+			let on_chain_version = Pallet::<T>::on_chain_storage_version();
+			ensure!(on_chain_version < 1, "assigned_slots::MigrateToV1 migration can be deleted");
 			Ok(Default::default())
 		}
 
 		fn on_runtime_upgrade() -> frame_support::weights::Weight {
-			let onchain_version = Pallet::<T>::on_chain_storage_version();
-			if onchain_version < 1 {
+			let on_chain_version = Pallet::<T>::on_chain_storage_version();
+			if on_chain_version < 1 {
 				const MAX_PERMANENT_SLOTS: u32 = 100;
 				const MAX_TEMPORARY_SLOTS: u32 = 100;
 
@@ -52,8 +52,8 @@ pub mod v1 {
 
 		#[cfg(feature = "try-runtime")]
 		fn post_upgrade(_state: Vec<u8>) -> Result<(), sp_runtime::TryRuntimeError> {
-			let onchain_version = Pallet::<T>::on_chain_storage_version();
-			ensure!(onchain_version == 1, "assigned_slots::MigrateToV1 needs to be run");
+			let on_chain_version = Pallet::<T>::on_chain_storage_version();
+			ensure!(on_chain_version == 1, "assigned_slots::MigrateToV1 needs to be run");
 			assert_eq!(<MaxPermanentSlots<T>>::get(), 100);
 			assert_eq!(<MaxTemporarySlots<T>>::get(), 100);
 			Ok(())

polkadot/runtime/common/src/assigned_slots/mod.rs

@@ -107,7 +107,7 @@ type LeasePeriodOf<T> = <<T as Config>::Leaser as Leaser<BlockNumberFor<T>>>::Le
 pub mod pallet {
 	use super::*;
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
 
 	#[pallet::pallet]

polkadot/runtime/common/src/crowdloan/migration.rs

@@ -24,9 +24,9 @@ use frame_support::{
 pub struct MigrateToTrackInactiveV2<T>(sp_std::marker::PhantomData<T>);
 impl<T: Config> OnRuntimeUpgrade for MigrateToTrackInactiveV2<T> {
 	fn on_runtime_upgrade() -> Weight {
-		let onchain_version = Pallet::<T>::on_chain_storage_version();
+		let on_chain_version = Pallet::<T>::on_chain_storage_version();
 
-		if onchain_version == 1 {
+		if on_chain_version == 1 {
 			let mut translated = 0u64;
 			for item in Funds::<T>::iter_values() {
 				let b =

polkadot/runtime/common/src/crowdloan/mod.rs

@@ -180,7 +180,7 @@ pub mod pallet {
 	use frame_support::pallet_prelude::*;
 	use frame_system::{ensure_root, ensure_signed, pallet_prelude::*};
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(2);
 
 	#[pallet::pallet]

polkadot/runtime/common/src/paras_registrar/mod.rs

@@ -106,7 +106,7 @@ pub mod pallet {
 	use frame_support::pallet_prelude::*;
 	use frame_system::pallet_prelude::*;
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
 
 	#[pallet::pallet]