Update to frame-metadata 22 (#8327)

The main change in [the proposed
`frame-metadata@22`](paritytech/frame-metadata#101)
is that the deprecation information was tidied to remove some possible
but confusing states, which simplifies making use of it in client code.

One change made in the process is that **the ability to deprecate the
entire of the Call/Error/Event enum was removed**.

In other words, prior to this change a pallet author could do either of
these:

```rust
/// Deprecate the entire enum (but this is ignored if any variants are deprecated):
#[deprecated(note = "This is deprecated")]
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config<I>, I: 'static = ()> {
    /// An account was created with some free balance.
    Endowed { account: T::AccountId, free_balance: T::Balance },
    /// An account was removed whose balance was non-zero but below ExistentialDeposit,
    /// resulting in an outright loss.
    DustLost { account: T::AccountId, amount: T::Balance },
}

/// Deprecate individual variants:
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config<I>, I: 'static = ()> {
    /// An account was created with some free balance.
    #[deprecated(note = "This is deprecated")]
    Endowed { account: T::AccountId, free_balance: T::Balance },
    /// An account was removed whose balance was non-zero but below ExistentialDeposit,
    /// resulting in an outright loss.
    #[deprecated(note = "This is deprecated too")]
    DustLost { account: T::AccountId, amount: T::Balance },
}
```

After this PR, **a pallet author can still deprecate individual
variants, but not the entire enum**.

Some reasoning behind this change:
1. It's unlikely that the entire of these enums would ever be entirely
deprecated.
2. In the case of calls, there is no obvious place to put such a warning
anyway.
3. Sticking to just deprecating variants makes it a little simpler for
client code; fewer cases to handle during codegen or whatever.
4. Avoid a confusing state where `#[deprecation]` can be put on the
entire enum _and_ some variants, which leads to the enum-wide
deprecation warning being ignored.

See paritytech/frame-metadata#100 for some
more context on the changes.

# Notes

This PR currently pulls `frame-metadata` via a github branch, for
testing purposes. If we are happy here, I'll merge that PR, release
`frame-metadata` and remove the github dependency before we merge this.

Author: jsdw

Cargo.lock

@@ -800,7 +800,7 @@ frame-benchmarking-pallet-pov = { default-features = false, path = "substrate/fr
 frame-election-provider-solution-type = { path = "substrate/frame/election-provider-support/solution-type", default-features = false }
 frame-election-provider-support = { path = "substrate/frame/election-provider-support", default-features = false }
 frame-executive = { path = "substrate/frame/executive", default-features = false }
-frame-metadata = { version = "21.0.0", default-features = false }
+frame-metadata = { version = "22.0.0", default-features = false }
 frame-metadata-hash-extension = { path = "substrate/frame/metadata-hash-extension", default-features = false }
 frame-support = { path = "substrate/frame/support", default-features = false }
 frame-support-procedural = { path = "substrate/frame/support/procedural", default-features = false }

Cargo.toml

@@ -0,0 +1,13 @@
+title: Update to the latest unstable V16 metadata.
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      The frame-metadata version is bumped to v22 to bring in the latest unstable V16 metadata format. Notably,
+      deprecation information has changed slightly, and deprecation notices on the outer Event/Error enums
+      are no longer supported (but each variant can still be marked as deprecated).
+
+
+crates:
+  - name: sp-metadata-ir
+    bump: major

prdoc/pr_8327.prdoc

@@ -28,7 +28,7 @@ use scale_info::meta_type;
 use frame_support::{derive_impl, pallet_prelude::PalletInfoAccess, view_functions::ViewFunction};
 use sp_io::hashing::twox_128;
 use sp_metadata_ir::{
-	DeprecationStatusIR, PalletViewFunctionMetadataIR, PalletViewFunctionParamMetadataIR,
+	ItemDeprecationInfoIR, PalletViewFunctionMetadataIR, PalletViewFunctionParamMetadataIR,
 };
 use sp_runtime::testing::TestXt;
 
@@ -144,7 +144,7 @@ fn metadata_ir_definitions() {
 					inputs: vec![],
 					output: meta_type::<Option<u32>>(),
 					docs: vec![" Query value with no input args."],
-					deprecation_info: DeprecationStatusIR::NotDeprecated,
+					deprecation_info: ItemDeprecationInfoIR::NotDeprecated,
 				},
 				PalletViewFunctionMetadataIR {
 					name: "get_value_with_arg",
@@ -155,7 +155,7 @@ fn metadata_ir_definitions() {
 					},],
 					output: meta_type::<Option<u32>>(),
 					docs: vec![" Query value with input args."],
-					deprecation_info: DeprecationStatusIR::NotDeprecated,
+					deprecation_info: ItemDeprecationInfoIR::NotDeprecated,
 				},
 			]
 		);

substrate/frame/examples/view-functions/src/tests.rs

@@ -36,7 +36,28 @@ fn deprecation_msg_formatter(msg: &str) -> String {
 	)
 }
 
-fn parse_deprecated_meta(crate_: &TokenStream, attr: &syn::Attribute) -> Result<TokenStream> {
+// Should we generate a #crate_::__private::metadata_ir::ItemDeprecationInfoIR
+// or a #crate_::__private::metadata_ir::VariantDeprecationInfoIR? In other words,
+// are we targeting variant deprecation information, or generic item deprecation
+// information.
+#[derive(Copy, Clone, PartialEq)]
+enum DeprecationTarget {
+	Item,
+	Variant,
+}
+
+fn parse_deprecated_meta(
+	crate_: &TokenStream,
+	attr: &syn::Attribute,
+	target: DeprecationTarget,
+) -> Result<TokenStream> {
+	let target = match target {
+		DeprecationTarget::Item =>
+			quote! { #crate_::__private::metadata_ir::ItemDeprecationInfoIR },
+		DeprecationTarget::Variant =>
+			quote! { #crate_::__private::metadata_ir::VariantDeprecationInfoIR },
+	};
+
 	match &attr.meta {
 		Meta::List(meta_list) => {
 			let parsed = meta_list
@@ -60,14 +81,19 @@ fn parse_deprecated_meta(crate_: &TokenStream, attr: &syn::Attribute) -> Result<
 				Ok::<(Option<&syn::Lit>, Option<&syn::Lit>), Error>(acc)
 			})?;
 			note.map_or_else(
-		  || Err(Error::new(attr.span(), deprecation_msg_formatter("Invalid deprecation attribute: missing `note`"))),
+				|| {
+					Err(Error::new(
+						attr.span(),
+						deprecation_msg_formatter("Invalid deprecation attribute: missing `note`"),
+					))
+				},
 				|note| {
 					let since = if let Some(str) = since {
 						quote! { Some(#str) }
 					} else {
 						quote! { None }
 					};
-					let doc = quote! { #crate_::__private::metadata_ir::DeprecationStatusIR::Deprecated { note: #note, since: #since }};
+					let doc = quote! { #target::Deprecated { note: #note, since: #since }};
 					Ok(doc)
 				},
 			)
@@ -77,14 +103,12 @@ fn parse_deprecated_meta(crate_: &TokenStream, attr: &syn::Attribute) -> Result<
 			..
 		}) => {
 			// #[deprecated = "lit"]
-			let doc = quote! { #crate_::__private::metadata_ir::DeprecationStatusIR::Deprecated { note: #lit, since: None } };
+			let doc = quote! { #target::Deprecated { note: #lit, since: None } };
 			Ok(doc)
 		},
 		Meta::Path(_) => {
 			// #[deprecated]
-			Ok(
-				quote! { #crate_::__private::metadata_ir::DeprecationStatusIR::DeprecatedWithoutNote },
-			)
+			Ok(quote! { #target::DeprecatedWithoutNote })
 		},
 		_ => Err(Error::new(
 			attr.span(),
@@ -93,50 +117,60 @@ fn parse_deprecated_meta(crate_: &TokenStream, attr: &syn::Attribute) -> Result<
 	}
 }
 
+fn find_deprecation_attr(attrs: &[syn::Attribute]) -> Option<&syn::Attribute> {
+	attrs.iter().find(|a| a.path().is_ident("deprecated"))
+}
+
+fn parse_deprecation(
+	path: &TokenStream,
+	attrs: &[syn::Attribute],
+	target: DeprecationTarget,
+) -> Result<Option<TokenStream>> {
+	find_deprecation_attr(attrs)
+		.map(|a| parse_deprecated_meta(path, a, target))
+		.transpose()
+}
+
 /// collects deprecation attribute if its present.
 pub fn get_deprecation(path: &TokenStream, attrs: &[syn::Attribute]) -> Result<TokenStream> {
-	parse_deprecation(path, attrs).map(|item| {
+	parse_deprecation(path, attrs, DeprecationTarget::Item).map(|item| {
 		item.unwrap_or_else(|| {
-			quote! {#path::__private::metadata_ir::DeprecationStatusIR::NotDeprecated}
+			quote! {#path::__private::metadata_ir::ItemDeprecationInfoIR::NotDeprecated}
 		})
 	})
 }
 
-fn parse_deprecation(path: &TokenStream, attrs: &[syn::Attribute]) -> Result<Option<TokenStream>> {
-	attrs
-		.iter()
-		.find(|a| a.path().is_ident("deprecated"))
-		.map(|a| parse_deprecated_meta(path, a))
-		.transpose()
+/// Call this on enum attributes to return an error if the #[deprecation] attribute is found.
+pub fn prevent_deprecation_attr_on_outer_enum(parent_attrs: &[syn::Attribute]) -> Result<()> {
+	if let Some(attr) = find_deprecation_attr(parent_attrs) {
+		return Err(Error::new(
+			attr.span(),
+			"The `#[deprecated]` attribute should be applied to individual variants, not the enum as a whole.",
+		));
+	}
+	Ok(())
 }
 
 /// collects deprecation attribute if its present for enum-like types
 pub fn get_deprecation_enum<'a>(
 	path: &TokenStream,
-	parent_attrs: &[syn::Attribute],
 	children_attrs: impl Iterator<Item = (u8, &'a [syn::Attribute])>,
 ) -> Result<TokenStream> {
-	let parent_deprecation = parse_deprecation(path, parent_attrs)?;
-
 	let children = children_attrs
 		.filter_map(|(key, attributes)| {
-			let key = quote::quote! { #path::__private::codec::Compact(#key as u8) };
-			let deprecation_status = parse_deprecation(path, attributes).transpose();
+			let deprecation_status =
+				parse_deprecation(path, attributes, DeprecationTarget::Variant).transpose();
 			deprecation_status.map(|item| item.map(|item| quote::quote! { (#key, #item) }))
 		})
 		.collect::<Result<Vec<TokenStream>>>()?;
-	match (parent_deprecation, children.as_slice()) {
-		(None, []) =>
-			Ok(quote::quote! { #path::__private::metadata_ir::DeprecationInfoIR::NotDeprecated }),
-		(None, _) => {
-			let children = quote::quote! { #path::__private::scale_info::prelude::collections::BTreeMap::from([#( #children),*]) };
-			Ok(
-				quote::quote! { #path::__private::metadata_ir::DeprecationInfoIR::VariantsDeprecated(#children) },
-			)
-		},
-		(Some(depr), _) => Ok(
-			quote::quote! { #path::__private::metadata_ir::DeprecationInfoIR::ItemDeprecated(#depr) },
-		),
+
+	if children.is_empty() {
+		Ok(
+			quote::quote! { #path::__private::metadata_ir::EnumDeprecationInfoIR::nothing_deprecated() },
+		)
+	} else {
+		let children = quote::quote! { #path::__private::scale_info::prelude::collections::BTreeMap::from([#( #children),*]) };
+		Ok(quote::quote! { #path::__private::metadata_ir::EnumDeprecationInfoIR(#children) })
 	}
 }
 

substrate/frame/support/procedural/src/deprecation.rs

@@ -265,7 +265,6 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 
 	let deprecation = match crate::deprecation::get_deprecation_enum(
 		&quote::quote! {#frame_support},
-		def.call.as_ref().map(|call| call.attrs.as_ref()).unwrap_or(&[]),
 		methods.iter().map(|item| (item.call_index as u8, item.attrs.as_ref())),
 	) {
 		Ok(deprecation) => deprecation,

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

@@ -106,7 +106,6 @@ pub fn expand_error(def: &mut Def) -> proc_macro2::TokenStream {
 
 	let deprecation = match crate::deprecation::get_deprecation_enum(
 		&quote::quote! {#frame_support},
-		&error.attrs,
 		error_item.variants.iter().enumerate().map(|(index, item)| {
 			let index = crate::deprecation::variant_index_for_deprecation(index as u8, item);
 

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

@@ -98,7 +98,6 @@ pub fn expand_event(def: &mut Def) -> proc_macro2::TokenStream {
 
 	let deprecation = match crate::deprecation::get_deprecation_enum(
 		&quote::quote! {#frame_support},
-		&event.attrs,
 		event_item.variants.iter().enumerate().map(|(index, item)| {
 			let index = crate::deprecation::variant_index_for_deprecation(index as u8, item);
 

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

@@ -300,7 +300,7 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream {
 		impl<#type_use_gen> #pallet_ident<#type_use_gen> {
 			#[allow(dead_code)]
 			#[doc(hidden)]
-			pub fn deprecation_info() -> #frame_support::__private::metadata_ir::DeprecationStatusIR {
+			pub fn deprecation_info() -> #frame_support::__private::metadata_ir::ItemDeprecationInfoIR {
 				#deprecation_status
 			}
 		}

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

@@ -51,8 +51,6 @@ pub struct CallDef {
 	pub docs: Vec<syn::Expr>,
 	/// The optional `weight` attribute on the `pallet::call`.
 	pub inherited_call_weight: Option<InheritedCallWeightAttr>,
-	/// attributes
-	pub attrs: Vec<syn::Attribute>,
 }
 
 /// The weight of a call.
@@ -220,6 +218,9 @@ impl CallDef {
 		} else {
 			return Err(syn::Error::new(item.span(), "Invalid pallet::call, expected item impl"));
 		};
+
+		crate::deprecation::prevent_deprecation_attr_on_outer_enum(&item_impl.attrs)?;
+
 		let instances = vec![
 			helper::check_impl_gen(&item_impl.generics, item_impl.impl_token.span())?,
 			helper::check_pallet_struct_usage(&item_impl.self_ty)?,
@@ -461,7 +462,6 @@ impl CallDef {
 			where_clause: item_impl.generics.where_clause.clone(),
 			docs: get_doc_literals(&item_impl.attrs),
 			inherited_call_weight,
-			attrs: item_impl.attrs.clone(),
 		})
 	}
 }