Re: deprecated handling - reloaded

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

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
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org

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