I opened bug 59804 to start working on a @Removal decorator, unit tests that generate warnings when a deprecated method that has become eligible for removal remains in POI. On Jun 17, 2016 02:12, "Javen O'Neal" <[email protected]> wrote:
> On 2015-11-24, Andreas Beeker said: > > So lets assume we add a version comment to each deprecated element for a > later removal. > > In this case we have to check the logic twice, when deprecating it and > when removing it. > > As I've been deleting long-since deprecated methods and classes, I > have gained an appreciation for javadocs which specified what replaces > the deprecated method. If it's more complicated than adding or > removing a parameter, reordering the parameters, changing the spelling > of a method, or using a 1:1 replacement (a method that returns the > width in pixels as a double rather than 1/256 of a point), then there > really does need to be a deprecation notice and an explanation to help > users upgrade their code. > > Even if users jump 5 POI versions at a time, they could do that by > jumping 2 versions at a time or jump the entire distance and bisect > the docs to know how to upgrade their code (classes getting added, > removed, renamed, relocated, consolidated, split, etc). It is too much > to ask users to read through the changelog for all the skipped > versions, the comments and attachments for each bug associated with an > item in the changelog, and the commits made for those bugs (which may > not have been referenced in the bug) to understand what class or > method replaced the class or method they were using. > > Even for trivial replacements, the commit before removing a > method/class should show what the replacement is--though preferably > that deprecation warning would linger for at least 1 if not 2 final > releases. > > On Wed, Nov 25, 2015 at 1:57 AM, David North <[email protected]> > wrote: > > On 25/11/15 06:40, Javen O'Neal wrote: > >> Tldr: > >> Here's what I propose: > >> 1) contributors should add dates and/or POI versions to @deprecated > >> annotations for new commits > >> 2) contributors should add @since version annotations to new features > >> 3) new features may be removed without deprecation only if added prior > to a > >> final build and removed before or during the next final build (same > release > >> series) > > Makes sense to me. > >> ... > >> Can we automatically check for `@deprecated <release version or date>` > or > >> `@since <release version>` in Jenkins? > > > > That's crucial in my view: we've got to have automated enforcement that > > this kind of metadata is being kept accurate and acted upon, otherwise > > it will rapidly become an out of date embarassement. > > > > A bit of Googling doesn't come up with any obvious tools for inspecting > > the deprecated tag in JavaDoc, however if we did something like this:- > > > > * Use the @Deprecated annotation in addition to the JavaDoc tag (which > > is useful for some IDEs anyway) > > * Invent our own @Removal annodation to contain the date/POI version of > > expected removal > > > > Then it would be easy to write a functional test which used reflection > > to check all @Deprecated annotated elements had an @Removal too, and to > > tell us when things come up as due to be removed. > > > > David > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > >
