Mailing-List: contact dev-help@poi.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "POI Developers List" <dev@poi.apache.org>
MIME-Version: 1.0
In-Reply-To: <56558606.7070608@corefiling.co.uk>
References: <56550453.7030407@apache.org> <CAM+Tpp+w8a0bu6vTtT0=hCUWm8TEe1TFCSr_1B08a-rXqhUm7g@mail.gmail.com>
 <56558606.7070608@corefiling.co.uk>
From: "Javen O'Neal" <javenoneal@gmail.com>
Date: Fri, 17 Jun 2016 02:12:30 -0700
Message-ID: <CAM+TppLsagEGZF4hgW4zikk6xk2xnp5ZqKUOJjx4AR3c2EiTRA@mail.gmail.com>
Subject: Re: deprecated handling - reloaded
To: POI Developers List <dev@poi.apache.org>
Content-Type: text/plain; charset=UTF-8
archived-at: Fri, 17 Jun 2016 09:13:17 -0000

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 <dtn-poi@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