commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Date Tue, 24 Dec 2013 11:22:12 GMT
On 24 December 2013 08:51, Benedikt Ritter <britter@apache.org> wrote:
> Hi,
>
> we have this API breakage in FastDateFormat between 3.1 and the upcoming
> 3.2 release [1]. Gary suggested to make this explicit in the JavaDoc of
> FastDateFormat [2].
>
> I personally don't like this idea for the following reasons:
> - JavaDoc is about the functionality of a class. It is no migration guide.
> - The information already is in two places: RELEASE_NOTES and Clirr
> - In this special case it is very unlikely that users will even notice this
> breakage.
>
> I like to hear other opinions on this before I cut the next release.

I agree with you; having the information in Javadoc is not appropriate.
For one thing, it only applies to this release. The text would need to
be removed for the next release.

It would be nice if the Clirr report accepted additional text to
explain why the errors are OK, but I don't think it does.
However it would perhaps be worth adding a note to the index page in
the section headed "Release Information".
This could say something like:

The Clirr report for release 3.2 shows some errors.
These are not considered to affect the public API; please see the
[release notes] for details.

[release notes] should be a link if possible.

> Regards,
> Benedikt
>
> [1]
> http://people.apache.org/~britter/commons-lang3/3.2-RC1/site/clirr-report.html
> [2] http://markmail.org/message/twzwuwmjddggnodx
>
>
> --
> http://people.apache.org/~britter/
> http://www.systemoutprintln.de/
> http://twitter.com/BenediktRitter
> http://github.com/britter

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


Mime
View raw message