[doc] Keep record of every currently deprecated API #1284
Labels
a:RFC
A drafted proposal on changes to PMD, up for feedback form the team and community
in:documentation
Affects the documentation
Milestone
We already have some version of this in #881, but this is only meant for us maintainers and not users. Every time we deprecate something, we add an explanation in the release notes, which is nicer. We could sum up every currently deprecated APIs in a single page on the website. This could help users plan a migration to the next major release, and help keep track of every deprecated rule and APIs and why they're deprecated.
Basically this page would include the release notes explanations for every deprecated API since the last major version. Maintaining this page would only involve copying these explanations from the latest release notes into the page every time we push a release.
Related to #995: if we start massively deprecating internal apis, this new page could directly provide added value for users and for us
We could also extend that bookkeeping to features we add, basically maintaining a page listing all the cool things that were added since the last major release, to encourage migration to the latest version.
Note @jsotuyod
we discussed that in the last meeting
Possible future improvements
I'm thinking that we may automate that copying process at some point if we used a yaml file to keep track of deprecated things, and generate the page with simple scripts.
Stretching the idea even further, we could also think about a scheme to fit every release note update into a yaml format and generate the release notes entirely automatically from these description files. If we did that, we may add a tool on the website to expose the full feature and api "diff" between any two versions. Not sure this is very relevant
The text was updated successfully, but these errors were encountered: