-
Notifications
You must be signed in to change notification settings - Fork 667
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Extend metadata with deprecation #4098
Comments
Solution B sounds more reasonable to me, but before doing this I would like to discuss two things:
|
So in regards to PJS, the docs provided in the metadata are augmented as comments as part of the call when its generated for the API. Example. So if there is a deprecation in the docs it will appear in the comments.
I think this would need very specific formatting. For example, prefixing the deprecated string with some sort of symbol like In regards to the other proposed solutions:
|
For 1, we could borrow from a format a bit like TSDoc or whatever and have |
we remove all the comments from metadata to reduce wasm size so M is not an option |
Sorry; I was somewhat distracted yesterday and didn't elaborate much. Overall, I'm generally in favour of adding deprecation tags to things in the metadata so that you get the nice tooling warnings, and in the long term would prob aim for A, eg adding a A couple of questions if we were to go for A:
If we want to add this then we'll need to work towards a metadata V16. Since we don't want to release new metadata versions too often (IMO), we'd also want to gather up what else should make it into V16 (eg maybe also information to help reduce the config needed in tools like Subxt). So if we want this sooner rather than later then maybe this is a good chance to use the custom metadata field first to add some information without needing to update to V16. For that, we could add a type something like this: enum DeprecatedIdentifier {
Pallet { index: u8 },
Tx { pallet_index: u8, call_index: u8 },
// .. enough info to point to the thing that's deprecated
}
struct DeprecatedStatuses {
statuses: BTreeMap<DeprecatedIdentifier, DeprecatedStatus>
} And then tooling can look up the relevant value for a given tx etc to see what its deprecation status is. I'm expecting that we'll be looking at V16 metadata in Q3/Q4 and what to add etc this year, so perhaps it won't be tooo long! |
### Description: * Adds `DeprecationStatusIR` enum to sp_metadata_ir. Deprecation info for simple items. * Adds `DeprecationInfoIR` enum to sp_metadata_ir. It is a deprecation info for an enums/errors/calls. Contains `DeprecationStatusIR`. Denotes full/partial deprecation of the type or its variants/calls * Adds `deprecation_info` field to - `RuntimeApiMetadataIR` - `RuntimeApiMethodMetadataIR` - `StorageEntryMetadataIR` - `PalletConstantMetadataIR` - `PalletCallMetadataIR` - `PalletMetadataIR` - `PalletEventMetadataIR` - `PalletErrorMetadataIR` ### Testing done: - Unit tests to check whether or not correct `note`/`since` texts are getting propagated to the metadata structs. - UI test to check for error message in case of incorrect attribute usage. There's also some test updates to make sure that deprecation attributes are getting propagated to the relevant structs. see: #4098, Solution: A ### Examples of produced deprecation info metadata They can be found in: - Tests for `frame-support` - hackmd link https://hackmd.io/@Zett98/Bys0YgbcR --------- Co-authored-by: GitHub Action <[email protected]> Co-authored-by: command-bot <> Co-authored-by: Bastian Köcher <[email protected]>
Is there an existing issue?
Experiencing problems? Have you tried our Stack Exchange first?
Motivation
As a dApp/tooling developer interacting with the blockchain through JS libraries and RPCs, there are no warnings or any information letting you know that a method you're using is deprecated.
No such information is included in metadata or RPC responses, so there is no way to programmatically read this information.
The only way to realize you're using a deprecated method is to follow the chain:
polkadot-sdk
release including a PR that marks a given method as deprecated.runtimes
release that upgradespolkadot-sdk
to thispolkadot-sdk
release.runtimes
release.Only following this chain of releases you can realize that a method you're using without any warning or issues starts being deprecated.
It can fail for many reasons (either from insufficiently propagating deprecation/breaking-changes information down this list, or from developer failing to keep himself up to date). I posted some more thoughts here.
Because of that, I think that there is a lack of deprecation information that can be consumed programmatically when running a program and interacting with the chain.
Request
I'm requesting for deprecation information to be included in the metadata.
With that, the libraries such as PJS could read it and warn the developer that he's using a deprecated method automatically.
Solution
Solution M (for minimal)
In the metadata, there is a text field
docs
. It could be enforced to have adeprecated
string in this text, if a method is marked as deprecated in Rust. That could be a start.Solution A
Add a dedicated
deprecated
field to metadata for for calls, events, errors and storage items - as posted here by @kianenigma.Solution B
Add a custom metadata field, which could also be used for this purpose with a specified custom metadata key - as posted here by @xlc.
Are you willing to help with this request?
Yes!
The text was updated successfully, but these errors were encountered: