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/procedural/src/lib.rs

@@ -555,6 +555,42 @@ pub fn __create_tt_macro(input: TokenStream) -> TokenStream {
 	tt_macro::create_tt_return_macro(input)
 }
 
+/// Allows accessing on-chain pallet storage that is no longer accessible via the pallet.
+///
+/// This is especially useful when writing storage migrations, when types of storage items are
+/// modified or outright removed, but the previous definition is required to perform the migration.
+///
+/// ## Example
+///
+/// Imagine a pallet with the following storage definition:
+/// ```ignore
+/// #[pallet::storage]
+/// pub type Value<T: Config> = StorageValue<_, u32>;
+/// ```
+/// `Value` can be accessed by calling `Value::<T>::get()`.
+///
+/// Now imagine the definition of `Value` is updated to a `(u32, u32)`:
+/// ```ignore
+/// #[pallet::storage]
+/// pub type Value<T: Config> = StorageValue<_, (u32, u32)>;
+/// ```
+/// The on-chain value of `Value` is `u32`, but `Value::<T>::get()` expects it to be `(u32, u32)`.
+///
+/// In this instance the developer must write a storage migration to reading the old value of
+/// `Value` and writing it back to storage in the new format, so that the on-chain storage layout is
+/// consistent with what is defined in the pallet.
+///
+/// We can read the old v0 value of `Value` in the migration by creating a `storage_alias`:
+/// ```ignore
+/// pub(crate) mod v0 {
+/// 	use super::*;
+///
+/// 	#[storage_alias]
+/// 	pub type Value<T: crate::Config> = StorageValue<crate::Pallet<T>, u32>;
+/// }
+/// ```
+///
+/// The developer can now access the old value of `Value` by calling `v0::Value::<T>::get()`.
 #[proc_macro_attribute]
 pub fn storage_alias(attributes: TokenStream, input: TokenStream) -> TokenStream {
 	storage_alias::storage_alias(attributes.into(), input.into())
@@ -1058,7 +1094,7 @@ pub fn generate_store(_: TokenStream, _: TokenStream) -> TokenStream {
 /// pub struct Pallet<T>(_);
 /// ```
 ///
-/// If not present, the current storage version is set to the default value.
+/// If not present, the in-code storage version is set to the default value.
 #[proc_macro_attribute]
 pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream {
 	pallet_macro_stub()

substrate/frame/support/procedural/src/pallet/expand/hooks.rs

@@ -42,7 +42,7 @@ pub fn expand_hooks(def: &mut Def) -> proc_macro2::TokenStream {
 		>::name::<Self>().unwrap_or("<unknown pallet name>")
 	};
 
-	let initialize_on_chain_storage_version = if let Some(current_version) =
+	let initialize_on_chain_storage_version = if let Some(in_code_version) =
 		&def.pallet_struct.storage_version
 	{
 		quote::quote! {
@@ -50,9 +50,9 @@ pub fn expand_hooks(def: &mut Def) -> proc_macro2::TokenStream {
 				target: #frame_support::LOG_TARGET,
 				"🐥 New pallet {:?} detected in the runtime. Initializing the on-chain storage version to match the storage version defined in the pallet: {:?}",
 				#pallet_name,
-				#current_version
+				#in_code_version
 			);
-			#current_version.put::<Self>();
+			#in_code_version.put::<Self>();
 		}
 	} else {
 		quote::quote! {
@@ -73,10 +73,10 @@ pub fn expand_hooks(def: &mut Def) -> proc_macro2::TokenStream {
 			#frame_support::__private::log::info!(
 				target: #frame_support::LOG_TARGET,
 				"⚠️ {} declares internal migrations (which *might* execute). \
-				 On-chain `{:?}` vs current storage version `{:?}`",
+				 On-chain `{:?}` vs in-code storage version `{:?}`",
 				#pallet_name,
 				<Self as #frame_support::traits::GetStorageVersion>::on_chain_storage_version(),
-				<Self as #frame_support::traits::GetStorageVersion>::current_storage_version(),
+				<Self as #frame_support::traits::GetStorageVersion>::in_code_storage_version(),
 			);
 		}
 	} else {
@@ -102,23 +102,23 @@ pub fn expand_hooks(def: &mut Def) -> proc_macro2::TokenStream {
 	};
 
 	// If a storage version is set, we should ensure that the storage version on chain matches the
-	// current storage version. This assumes that `Executive` is running custom migrations before
+	// in-code storage version. This assumes that `Executive` is running custom migrations before
 	// the pallets are called.
 	let post_storage_version_check = if def.pallet_struct.storage_version.is_some() {
 		quote::quote! {
 			let on_chain_version = <Self as #frame_support::traits::GetStorageVersion>::on_chain_storage_version();
-			let current_version = <Self as #frame_support::traits::GetStorageVersion>::current_storage_version();
+			let in_code_version = <Self as #frame_support::traits::GetStorageVersion>::in_code_storage_version();
 
-			if on_chain_version != current_version {
+			if on_chain_version != in_code_version {
 				#frame_support::__private::log::error!(
 					target: #frame_support::LOG_TARGET,
-					"{}: On chain storage version {:?} doesn't match current storage version {:?}.",
+					"{}: On chain storage version {:?} doesn't match in-code storage version {:?}.",
 					#pallet_name,
 					on_chain_version,
-					current_version,
+					in_code_version,
 				);
 
-				return Err("On chain and current storage version do not match. Missing runtime upgrade?".into());
+				return Err("On chain and in-code storage version do not match. Missing runtime upgrade?".into());
 			}
 		}
 	} else {

substrate/frame/support/procedural/src/pallet/expand/pallet_struct.rs

@@ -160,7 +160,7 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream {
 		}
 	);
 
-	let (storage_version, current_storage_version_ty) =
+	let (storage_version, in_code_storage_version_ty) =
 		if let Some(v) = def.pallet_struct.storage_version.as_ref() {
 			(quote::quote! { #v }, quote::quote! { #frame_support::traits::StorageVersion })
 		} else {
@@ -203,9 +203,9 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream {
 			for #pallet_ident<#type_use_gen>
 			#config_where_clause
 		{
-			type CurrentStorageVersion = #current_storage_version_ty;
+			type InCodeStorageVersion = #in_code_storage_version_ty;
 
-			fn current_storage_version() -> Self::CurrentStorageVersion {
+			fn in_code_storage_version() -> Self::InCodeStorageVersion {
 				#storage_version
 			}
 

substrate/frame/support/procedural/src/pallet/parse/pallet_struct.rs

@@ -44,7 +44,7 @@ pub struct PalletStructDef {
 	/// Whether to specify the storages max encoded len when implementing `StorageInfoTrait`.
 	/// Contains the span of the attribute.
 	pub without_storage_info: Option<proc_macro2::Span>,
-	/// The current storage version of the pallet.
+	/// The in-code storage version of the pallet.
 	pub storage_version: Option<syn::Path>,
 }