Emit warnings for deprecated usages #1149
Description
Today we only communicate deprecated RPCAPI features through the RPCAPI documentation and the release notes. For an API user to realize that they're currently using one or more deprecated API features they need to know exactly which API features they're actually using and compare that to the documentation. This is not a reasonable assumption. This issue is about providing a better user experience.
- Describe in the RPCAPI documentation how warnings may be included in RPCAPI responses. Recommend that clients detect and log (or otherwise communicate) warnings emitted through this channel.
E.g. the "result" object of all RPCAPI responses could have an optional "warnings"-property with a non-empty list of human readable warning message strings. (By giving it a generic name like "warnings" we can reuse it later for some other kind of warnings should the need arise.) - Update the instructions for writing release notes to advertise that clients should support the warnings channel.
- In the deprecation policy prescribe that when an RPCAPI feature is deprecated, usage of that feature should be detected and emit a warning in the response.
- For each RPCAPI feature that is currently deprecated, update it according to the deprecation policy.
Stabilization
Affected interfaces
Compatibly changed:
- All RPCAPI methods
Dependencies
None
Overlapping proposals
None