commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Date Fri, 27 Dec 2013 14:04:49 GMT
Sorry for the top post, $!# phone. 

Yes the solution proposed is Ok but this begs the question: Are we now implying that all public
types and methods are really part of the public API? This solution also needs a statement
to answer this question. 

Gary

-------- Original message --------
From: Benedikt Ritter <britter@apache.org> 
Date:12/27/2013  07:51  (GMT-05:00) 
To: Commons Developers List <dev@commons.apache.org>,ggregory@apache.org 
Subject: Re: [LANG] Document API breakage in FastDateFormat in JavaDoc? 




2013/12/24 sebb <sebbaz@gmail.com>
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.

I'll try to bend the Clirr report this why, as soon as I get the time to cut RC 2 (probably
tomorrow).

Gary, since you were the one who raised this issue, are you okay with the proposed solution?

Regards,
Benedikt
 

> 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




-- 
http://people.apache.org/~britter/
http://www.systemoutprintln.de/
http://twitter.com/BenediktRitter
http://github.com/britter
Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message