Re: deprecated handling - reloaded

[Javen O'Neal <ja...@gmail.com>]

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" <ja...@gmail.com> 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 <dt...@corefiling.co.uk>
> 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: dev-unsubscribe@poi.apache.org
> > For additional commands, e-mail: dev-help@poi.apache.org
> >
>