Skip to content

[doc] Keep record of every currently deprecated API #1284

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

Closed
oowekyala opened this issue Aug 4, 2018 · 0 comments
Closed

[doc] Keep record of every currently deprecated API #1284

oowekyala opened this issue Aug 4, 2018 · 0 comments
Labels
a:RFC A drafted proposal on changes to PMD, up for feedback form the team and community in:documentation Affects the documentation
Milestone

Comments

@oowekyala
Copy link
Member

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

@oowekyala oowekyala added in:documentation Affects the documentation a:RFC A drafted proposal on changes to PMD, up for feedback form the team and community labels Aug 4, 2018
@oowekyala oowekyala changed the title [doc] Keep record of every currently deprecated API in PMD [doc] Keep record of every currently deprecated API Aug 4, 2018
@oowekyala oowekyala added this to the 6.10.0 milestone Nov 2, 2018
adangel added a commit that referenced this issue Nov 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
a:RFC A drafted proposal on changes to PMD, up for feedback form the team and community in:documentation Affects the documentation
Projects
None yet
Development

No branches or pull requests

1 participant