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

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

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

Comments

Projects
None yet
1 participant
@oowekyala
Copy link
Member

oowekyala commented Aug 4, 2018

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 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

@oowekyala oowekyala added the has:pr label 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