sp-api: Propagate deprecation information to metadata from impl_runtime_apis! blocks

[pkhry]

Description

Now its possible to deprecate an ApiTrait or a Method inside impl_runtime_apis! blocks.
If a deprecation attribute was present inside decl_runtime_apis! block then it is overriden with information from impl_runtime_apis! block.

ie:

decl_runtime_apis! {
           trait .... {
             #[deprecated = "test"] 
             fn example() {}
           }
}

impl_runtime_apis! {
          impl .... {
             #[deprecated = "overriden"] 
             fn example() {}
           }
}

The resulting deprecation string inside metadata for method example will be "overriden"

Review Notes

Adds additional argument to <trait_>::runtime_metadata to pass the deprecation information from the implementations.

[pkhry]

/cmd fmt

[github-actions]

Command "fmt" has started 🚀 See logs here

[github-actions]

Command "fmt" has finished ✅ See logs here

[bkchr]

If a deprecation attribute was present inside decl_runtime_apis! block then it is overriden with information from impl_runtime_apis! block.

Why should I override the deprecation notice in the impl block?

[pkhry]

If a deprecation attribute was present inside decl_runtime_apis! block then it is overriden with information from impl_runtime_apis! block.

Why should I override the deprecation notice in the impl block?

I guess I need to reword. In case of deprecation attribute being present on the same member in both decl_runtime_apis and impl_runtime_apis metadata will reflect deprecation info in the deprecation attribute used in the impl_runtime_api block

[bkchr]

Yeah, I mean I got this. My question still holds, why should I put a deprecate message into the impl block?

IMO we should do what rust is doing and return an error: rust-lang/rust#78626

[jsdw]

Yeah, I mean I got this. My question still holds, why should I put a deprecate message into the impl block?

My 2c:

In "normal" rust, it makes sense that deprecation attributes only exist on trait declarations: I define a trait and then want implementors of my trait to know if I am planning to remove some function of it, ie

#[deprecated]        'Warning: deprecated'
trait defintion ---> trait implementors

In this runtime stuff, we may want to inform runtime developers that some runtime API trait function is deprecated (via usual rust mechanisms), but also we want to inform users calling into a runtime that some part of the runtime interface is deprecated (via metadata), so we have two targets now ie

#[deprecated]         #[deprecated] + 'Warning'     'Warning'
trait definition ---> trait implementation      ---> Runtime API users 

And so, if I am a runtime developer, I may deprecate some Runtime API_implementations_ to signal that the runtime is moving to using some different Runtime APIs, or planning to jump to a newer version of some trait and stop supporting the older one, or just planning to remove some implementations entirely.

It also makes sense to me that #[deprecated] attrs on the definitions are passed to users to signal that those methods currently implemented by some runtime are also expected to go away.

[bkchr]

Yeah good argument. Maybe we should then differ between impl_deprecation and decl_deprecation?

[jsdw]

Yeah good argument. Maybe we should then differ between impl_deprecation and decl_deprecation?

I haven't though about this long enough, but offhand I can't think of a time when it would matter to users where the deprecation came from at the moment; only that the method was deprecated and then the reason for it, if provided.

[gui1117]

I agree that impl_deprecation is not really overriding decl_deprecation. But in practice I expect the impl_deprecation to be more precise than the decl_deprecation for runtime user so I think it is ok.

I have a concern in the review below, but apart from this it looks good to me

[gui1117]

I forgot, method names are unique or they are prefixed with the trait name in the runtime api?
If they are not unique and prefixed by the trait name we should do same here. Otherwise if 2 runtime API have a method with the same name then deprecation information will propagate to both.

You could even strongly type it to differentiate between trait deprecation and method deprecation, but it can be ok as it is.

[bkchr]

Same here

[paritytech-workflow-stopper]

All GitHub workflows were cancelled due to failure one of the required jobs.
Failed workflow url: https://github.com/paritytech/polkadot-sdk/actions/runs/17425996775
Failed job name: build-runtimes-polkavm