Deprecation info support in RuntimeMetadataIR

prdoc/pr_4851.prdoc

@@ -0,0 +1,20 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: Add support for deprecation metadata in `RuntimeMetadataIr` entries.
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      Adds `DeprecationStatus` enum to sp_metadata_ir.
+      Adds `deprecation_info` field to 
+       - `RuntimeApiMetadataIR`
+       - `RuntimeApiMethodMetadataIR`
+       - `StorageEntryMetadataIR`
+       - `PalletConstantMetadataIR`
+
+crates:
+  - name: frame-support-procedural
+  - name: frame-support
+  - name: sp-api-proc-macro
+  - name: sp-metadata-ir

substrate/frame/support/procedural/src/construct_runtime/parse.rs

@@ -139,9 +139,9 @@ impl Parse for WhereSection {
 			definitions.push(definition);
 			if !input.peek(Token![,]) {
 				if !input.peek(token::Brace) {
-					return Err(input.error("Expected `,` or `{`"))
+					return Err(input.error("Expected `,` or `{`"));
 				}
-				break
+				break;
 			}
 			input.parse::<Token![,]>()?;
 		}
@@ -154,7 +154,7 @@ impl Parse for WhereSection {
 				"`{:?}` was declared above. Please use exactly one declaration for `{:?}`.",
 				kind, kind
 			);
-			return Err(Error::new(*kind_span, msg))
+			return Err(Error::new(*kind_span, msg));
 		}
 		Ok(Self { span: input.span(), block, node_block, unchecked_extrinsic })
 	}
@@ -184,7 +184,7 @@ impl Parse for WhereDefinition {
 		} else if lookahead.peek(keyword::UncheckedExtrinsic) {
 			(input.parse::<keyword::UncheckedExtrinsic>()?.span(), WhereKind::UncheckedExtrinsic)
 		} else {
-			return Err(lookahead.error())
+			return Err(lookahead.error());
 		};
 
 		Ok(Self {
@@ -285,7 +285,7 @@ impl Parse for PalletDeclaration {
 		{
 			return Err(input.error(
 				"Unexpected tokens, expected one of `::{`, `exclude_parts`, `use_parts`, `=`, `,`",
-			))
+			));
 		} else {
 			is_expanded.then_some(extra_parts)
 		};
@@ -298,7 +298,7 @@ impl Parse for PalletDeclaration {
 			let _: keyword::use_parts = input.parse()?;
 			SpecifiedParts::Use(parse_pallet_parts_no_generic(input)?)
 		} else if !input.peek(Token![=]) && !input.peek(Token![,]) && !input.is_empty() {
-			return Err(input.error("Unexpected tokens, expected one of `exclude_parts`, `=`, `,`"))
+			return Err(input.error("Unexpected tokens, expected one of `exclude_parts`, `=`, `,`"));
 		} else {
 			SpecifiedParts::All
 		};
@@ -310,7 +310,7 @@ impl Parse for PalletDeclaration {
 			let index = index.base10_parse::<u8>()?;
 			Some(index)
 		} else if !input.peek(Token![,]) && !input.is_empty() {
-			return Err(input.error("Unexpected tokens, expected one of `=`, `,`"))
+			return Err(input.error("Unexpected tokens, expected one of `=`, `,`"));
 		} else {
 			None
 		};
@@ -354,7 +354,7 @@ impl Parse for PalletPath {
 			let ident = input.call(Ident::parse_any)?;
 			res.inner.segments.push(ident.into());
 		} else {
-			return Err(lookahead.error())
+			return Err(lookahead.error());
 		}
 
 		while input.peek(Token![::]) && input.peek3(Ident) {
@@ -385,7 +385,7 @@ fn parse_pallet_parts(input: ParseStream) -> Result<Vec<PalletPart>> {
 				"`{}` was already declared before. Please remove the duplicate declaration",
 				part.name(),
 			);
-			return Err(Error::new(part.keyword.span(), msg))
+			return Err(Error::new(part.keyword.span(), msg));
 		}
 	}
 
@@ -520,7 +520,7 @@ impl Parse for PalletPart {
 				keyword.name(),
 				valid_generics,
 			);
-			return Err(syn::Error::new(keyword.span(), msg))
+			return Err(syn::Error::new(keyword.span(), msg));
 		}
 
 		Ok(Self { keyword, generics })
@@ -581,7 +581,7 @@ fn parse_pallet_parts_no_generic(input: ParseStream) -> Result<Vec<PalletPartNoG
 				"`{}` was already declared before. Please remove the duplicate declaration",
 				part.keyword.name(),
 			);
-			return Err(Error::new(part.keyword.span(), msg))
+			return Err(Error::new(part.keyword.span(), msg));
 		}
 	}
 
@@ -665,7 +665,7 @@ enum PalletsConversion {
 /// incrementally from last explicit or 0.
 fn convert_pallets(pallets: Vec<PalletDeclaration>) -> syn::Result<PalletsConversion> {
 	if pallets.iter().any(|pallet| pallet.pallet_parts.is_none()) {
-		return Ok(PalletsConversion::Implicit(pallets))
+		return Ok(PalletsConversion::Implicit(pallets));
 	}
 
 	let mut indices = HashMap::new();
@@ -693,15 +693,15 @@ fn convert_pallets(pallets: Vec<PalletDeclaration>) -> syn::Result<PalletsConver
 				);
 				let mut err = syn::Error::new(used_pallet.span(), &msg);
 				err.combine(syn::Error::new(pallet.name.span(), msg));
-				return Err(err)
+				return Err(err);
 			}
 
 			if let Some(used_pallet) = names.insert(pallet.name.clone(), pallet.name.span()) {
 				let msg = "Two pallets with the same name!";
 
 				let mut err = syn::Error::new(used_pallet, &msg);
 				err.combine(syn::Error::new(pallet.name.span(), &msg));
-				return Err(err)
+				return Err(err);
 			}
 
 			let mut pallet_parts = pallet.pallet_parts.expect("Checked above");
@@ -727,7 +727,7 @@ fn convert_pallets(pallets: Vec<PalletDeclaration>) -> syn::Result<PalletsConver
 									}
 								})
 							);
-							return Err(syn::Error::new(part.keyword.span(), msg))
+							return Err(syn::Error::new(part.keyword.span(), msg));
 						}
 					},
 				SpecifiedParts::All => (),
@@ -753,7 +753,7 @@ fn convert_pallets(pallets: Vec<PalletDeclaration>) -> syn::Result<PalletsConver
 					if attr.path().segments.first().map_or(false, |s| s.ident != "cfg") {
 						let msg = "Unsupported attribute, only #[cfg] is supported on pallet \
 						declarations in `construct_runtime`";
-						return Err(syn::Error::new(attr.span(), msg))
+						return Err(syn::Error::new(attr.span(), msg));
 					}
 
 					attr.parse_args_with(|input: syn::parse::ParseStream| {

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

@@ -0,0 +1,105 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{
+	punctuated::Punctuated, spanned::Spanned, Error, Expr, ExprLit, Lit, Meta, MetaNameValue,
+	Result, Token,
+};
+fn deprecation_msg_formatter(msg: &str) -> String {
+	format!(
+		"{msg}\n{helper}",
+		msg = msg,
+		helper = r#"help: the following are the possible correct uses
+|
+|     #[deprecated = "reason"]
+|
+|     #[deprecated(/*opt*/ since = "version", /*opt*/ note = "reason")]
+|
+|     #[deprecated]
+|"#
+	)
+}
+
+fn parse_deprecated_meta(crate_: &TokenStream, attr: &syn::Attribute) -> Result<TokenStream> {
+	match &attr.meta {
+		Meta::List(meta_list) => {
+			let parsed = meta_list
+				.parse_args_with(Punctuated::<MetaNameValue, Token![,]>::parse_terminated)
+				.map_err(|e| Error::new(attr.span(), e.to_string()))?;
+			let (note, since) = parsed.iter().try_fold((None, None), |mut acc, item| {
+				let value = match &item.value {
+					Expr::Lit(ExprLit { lit: lit @ Lit::Str(_), .. }) => Ok(lit),
+					_ => Err(Error::new(
+						attr.span(),
+						deprecation_msg_formatter(
+							"Invalid deprecation attribute: expected string literal",
+						),
+					)),
+				}?;
+				if item.path.is_ident("note") {
+					acc.0.replace(value);
+				} else if item.path.is_ident("since") {
+					acc.1.replace(value);
+				} else {
+				};
+				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`"))),
+				|note| {
+					let since = if let Some(str) = since {
+						quote! { Some(#str) }
+					} else {
+						quote! { None }
+					};
+					let doc = quote! { #crate_::__private::metadata_ir::DeprecationStatus::Deprecated { note: #note, since: #since }};
+					Ok(doc)
+				},
+			)
+		},
+		Meta::NameValue(MetaNameValue {
+			value: Expr::Lit(ExprLit { lit: lit @ Lit::Str(_), .. }),
+			..
+		}) => {
+			// #[deprecated = "lit"]
+			let doc = quote! { #crate_::__private::metadata_ir::DeprecationStatus::Deprecated { note: #lit, since: None } };
+			Ok(doc)
+		},
+		Meta::Path(_) => {
+			// #[deprecated]
+			Ok(quote! { #crate_::__private::metadata_ir::DeprecationStatus::DeprecatedWithoutNote })
+		},
+		_ => Err(Error::new(
+			attr.span(),
+			deprecation_msg_formatter("Invalid deprecation attribute: expected string literal"),
+		)),
+	}
+}
+
+/// collects deprecation attribute if its present.
+pub fn get_deprecation(path: &TokenStream, attrs: &[syn::Attribute]) -> Result<TokenStream> {
+	attrs
+		.iter()
+		.find(|a| a.path().is_ident("deprecated"))
+		.map(|a| parse_deprecated_meta(path, a))
+		.unwrap_or_else(|| {
+			Ok(quote! {#path::__private::metadata_ir::DeprecationStatus::NotDeprecated})
+		})
+}

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

@@ -23,6 +23,7 @@
 mod benchmark;
 mod construct_runtime;
 mod crate_version;
+mod deprecation;
 mod derive_impl;
 mod dummy_part_checker;
 mod dynamic_params;
@@ -803,7 +804,7 @@ pub fn inject_runtime_type(_: TokenStream, tokens: TokenStream) -> TokenStream {
 			`RuntimeTask`, `RuntimeOrigin`, `RuntimeParameters` or `PalletInfo`",
 		)
 		.to_compile_error()
-		.into()
+		.into();
 	}
 	tokens
 }
@@ -1176,7 +1177,7 @@ pub fn import_section(attr: TokenStream, tokens: TokenStream) -> TokenStream {
 			"`#[import_section]` can only be applied to a valid pallet module",
 		)
 		.to_compile_error()
-		.into()
+		.into();
 	}
 
 	if let Some(ref mut content) = internal_mod.content {

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

@@ -28,6 +28,8 @@ struct ConstDef {
 	pub default_byte_impl: proc_macro2::TokenStream,
 	/// Constant name for Metadata (optional)
 	pub metadata_name: Option<syn::Ident>,
+	/// Deprecation_info:
+	pub deprecation_info: proc_macro2::TokenStream,
 }
 
 /// Implement the `pallet_constants_metadata` function for the pallet.
@@ -45,7 +47,9 @@ pub fn expand_constants(def: &mut Def) -> proc_macro2::TokenStream {
 	let config_consts = def.config.consts_metadata.iter().map(|const_| {
 		let ident = &const_.ident;
 		let const_type = &const_.type_;
-
+		let deprecation_info =
+			crate::deprecation::get_deprecation(&quote::quote! { #frame_support }, &const_.attrs)
+				.unwrap_or_else(syn::Error::into_compile_error);
 		ConstDef {
 			ident: const_.ident.clone(),
 			type_: const_.type_.clone(),
@@ -56,11 +60,15 @@ pub fn expand_constants(def: &mut Def) -> proc_macro2::TokenStream {
 				#frame_support::__private::codec::Encode::encode(&value)
 			),
 			metadata_name: None,
+			deprecation_info,
 		}
 	});
 
 	let extra_consts = def.extra_constants.iter().flat_map(|d| &d.extra_constants).map(|const_| {
 		let ident = &const_.ident;
+		let deprecation_info =
+			crate::deprecation::get_deprecation(&quote::quote! { #frame_support }, &const_.attrs)
+				.unwrap_or_else(syn::Error::into_compile_error);
 
 		ConstDef {
 			ident: const_.ident.clone(),
@@ -71,6 +79,7 @@ pub fn expand_constants(def: &mut Def) -> proc_macro2::TokenStream {
 				#frame_support::__private::codec::Encode::encode(&value)
 			),
 			metadata_name: const_.metadata_name.clone(),
+			deprecation_info,
 		}
 	});
 
@@ -82,13 +91,14 @@ pub fn expand_constants(def: &mut Def) -> proc_macro2::TokenStream {
 		let doc = if cfg!(feature = "no-metadata-docs") { &no_docs } else { &const_.doc };
 
 		let default_byte_impl = &const_.default_byte_impl;
-
+		let deprecation_info = &const_.deprecation_info;
 		quote::quote!({
 			#frame_support::__private::metadata_ir::PalletConstantMetadataIR {
 				name: #ident_str,
 				ty: #frame_support::__private::scale_info::meta_type::<#const_type>(),
 				value: { #default_byte_impl },
 				docs: #frame_support::__private::sp_std::vec![ #( #doc ),* ],
+				deprecation_info: #deprecation_info
 			}
 		})
 	});