deprecated handling - reloaded

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

deprecated handling - reloaded

kiwiwings
Hi,

this is partly a follow up to [1] and [2] - and sorry in advance to bring this up again,
but I feel we are too conservative.

Summary:
When we introduce new methods/enums/classes/... we try to be compile compatible with older versions.
After two releases the deprecated stuff can be removed.
Logic can be annotated internal, making it easier to change.

Does "release" mean a final or a beta release?
If it's a beta, it would probably make more sense to remove the deprecated stuff in the final release
and not spanning it over to the next final round. But then one could also drop the deprecated stuff
immediately, because it's just a beta ...

I'm not sure if the following conclusions based on the download stats [3] (only PMCs) are valid:
There's not much interest in betas after the final is out (... I know captain obvious is greeting)
3.9 is still quite frequently requested - the later version are approx. equally downloaded.
- are people are so slowly adapting, because the older version satisfy their needs?
- if we have the 2-release-deprecate-rule, does this really matter, i.e. are people gradually
  upgrading the version or do they jump over several releases anyway and need to be
  prepared for api breaks?

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.
I think this is tedious ... and the removing won't be done later ... having lots of deprecated stuff
around (see HWPF), which nobody wants to touch.

For X/HSLF I've decided to remove stuff immediately - having the scratchpad label as an excuse.

I try to think about a measure, when something should be kept available for longer or
can be removed immediately ... how about how often it used in the examples?
i.e. if less than 2 matches are found -> removed it
otherwise deprecate it

Best wishes,
Andi

[1] http://apache-poi.1045710.n5.nabble.com/Logging-Binary-compatibility-tt5719152.html
[2] https://bz.apache.org/bugzilla/show_bug.cgi?id=58636
[3] https://repository.apache.org/#central-stat

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: deprecated handling - reloaded

Dustin Spicuzza
From how we deal with Java releases at work... if it ain't broke, don't
bother updating. When you update, expect things to break. Also, for
those getting the releases via maven, it tends to encourage an ==
dependency, so you have to actively remember that you want to update the
package.

I think my impression is that most projects will mark things as
deprecated, but then (except in some cases) they often don't actually
remove them, so when I see them, I assume that I should avoid it, but if
I can't then it'll probably still be there for awhile. Guava explicitly
calls out what version they will remove deprecated stuff, so I tend to
take it more seriously. :)

Dustin


On 11/24/2015 07:44 PM, Andreas Beeker wrote:

> Hi,
>
> this is partly a follow up to [1] and [2] - and sorry in advance to bring this up again,
> but I feel we are too conservative.
>
> Summary:
> When we introduce new methods/enums/classes/... we try to be compile compatible with older versions.
> After two releases the deprecated stuff can be removed.
> Logic can be annotated internal, making it easier to change.
>
> Does "release" mean a final or a beta release?
> If it's a beta, it would probably make more sense to remove the deprecated stuff in the final release
> and not spanning it over to the next final round. But then one could also drop the deprecated stuff
> immediately, because it's just a beta ...
>
> I'm not sure if the following conclusions based on the download stats [3] (only PMCs) are valid:
> There's not much interest in betas after the final is out (... I know captain obvious is greeting)
> 3.9 is still quite frequently requested - the later version are approx. equally downloaded.
> - are people are so slowly adapting, because the older version satisfy their needs?
> - if we have the 2-release-deprecate-rule, does this really matter, i.e. are people gradually
>   upgrading the version or do they jump over several releases anyway and need to be
>   prepared for api breaks?
>
> 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.
> I think this is tedious ... and the removing won't be done later ... having lots of deprecated stuff
> around (see HWPF), which nobody wants to touch.
>
> For X/HSLF I've decided to remove stuff immediately - having the scratchpad label as an excuse.
>
> I try to think about a measure, when something should be kept available for longer or
> can be removed immediately ... how about how often it used in the examples?
> i.e. if less than 2 matches are found -> removed it
> otherwise deprecate it
>
> Best wishes,
> Andi
>
> [1] http://apache-poi.1045710.n5.nabble.com/Logging-Binary-compatibility-tt5719152.html
> [2] https://bz.apache.org/bugzilla/show_bug.cgi?id=58636
> [3] https://repository.apache.org/#central-stat
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: deprecated handling - reloaded

Javen O'Neal
In reply to this post by kiwiwings
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)

I really appreciate the folks who leave a date and/or POI version in the
Javadoc when deprecating the feature, as it makes removal much quicker [1].
I've been trying to remember to do so as well for my commits. I think it'd
also be good to add what version a feature was new in, so that users with
projects using an old version of POI, looking to use a feature that isn't
in their version of POI, know the bare minimum version they'd need to
upgrade to in order to get the feature. This may encourage people to
upgrade when they see how much cool stuff is in the newer versions.

Can we automatically check for `@deprecated <release version or date>` or
`@since <release version>` in Jenkins?

> After two releases the deprecated stuff can be removed.
> Does "release" mean a final or a beta release?
I'd say release means final release, and excludes beta. Companies that use
POI may choose not to run "beta" libraries in production applications, so
developers may ignore our beta releases until final comes out. If our
2-release rule included betas, this wouldn't give users a chance to see an
API go from supported to deprecated to removed in final-only upgrades. It
might be fair to say any feature that will be removed must be marked as
deprecated in at least 1 final release so that anyone can upgrade their
project one POI version at a time, and can check and fix deprecated
features. Holding onto deprecated features for at least 2 versions allows
users to catch up to the latest version by sequentially upgrading POI,
skipping every other version.
If users assume that any changes made in a beta build may change before
final release, then we have the flexibility to remove without first
deprecating any feature that was added in a beta version in the same
release series. As soon as a final is released, a feature should be
deprecated for one final release before removing.

[1] Side-note: viewvc's annotate/blame feature doesn't work for most files
On Nov 24, 2015 4:44 PM, "Andreas Beeker" <[hidden email]> wrote:

> Hi,
>
> this is partly a follow up to [1] and [2] - and sorry in advance to bring
> this up again,
> but I feel we are too conservative.
>
> Summary:
> When we introduce new methods/enums/classes/... we try to be compile
> compatible with older versions.
> After two releases the deprecated stuff can be removed.
> Logic can be annotated internal, making it easier to change.
>
> Does "release" mean a final or a beta release?
> If it's a beta, it would probably make more sense to remove the deprecated
> stuff in the final release
> and not spanning it over to the next final round. But then one could also
> drop the deprecated stuff
> immediately, because it's just a beta ...
>
> I'm not sure if the following conclusions based on the download stats [3]
> (only PMCs) are valid:
> There's not much interest in betas after the final is out (... I know
> captain obvious is greeting)
> 3.9 is still quite frequently requested - the later version are approx.
> equally downloaded.
> - are people are so slowly adapting, because the older version satisfy
> their needs?
> - if we have the 2-release-deprecate-rule, does this really matter, i.e.
> are people gradually
>   upgrading the version or do they jump over several releases anyway and
> need to be
>   prepared for api breaks?
>
> 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.
> I think this is tedious ... and the removing won't be done later ...
> having lots of deprecated stuff
> around (see HWPF), which nobody wants to touch.
>
> For X/HSLF I've decided to remove stuff immediately - having the
> scratchpad label as an excuse.
>
> I try to think about a measure, when something should be kept available
> for longer or
> can be removed immediately ... how about how often it used in the examples?
> i.e. if less than 2 matches are found -> removed it
> otherwise deprecate it
>
> Best wishes,
> Andi
>
> [1]
> http://apache-poi.1045710.n5.nabble.com/Logging-Binary-compatibility-tt5719152.html
> [2] https://bz.apache.org/bugzilla/show_bug.cgi?id=58636
> [3] https://repository.apache.org/#central-stat
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: deprecated handling - reloaded

David North
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: deprecated handling - reloaded

Javen O'Neal
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 <[hidden email]> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: deprecated handling - reloaded

Javen O'Neal
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" <[hidden email]> 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 <[hidden email]>
> 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: [hidden email]
> > For additional commands, e-mail: [hidden email]
> >
>