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 <[email protected]> Date:12/27/2013 07:51 (GMT-05:00) To: Commons Developers List <[email protected]>,[email protected] Subject: Re: [LANG] Document API breakage in FastDateFormat in JavaDoc? 2013/12/24 sebb <[email protected]> On 24 December 2013 08:51, Benedikt Ritter <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected] -- http://people.apache.org/~britter/ http://www.systemoutprintln.de/ http://twitter.com/BenediktRitter http://github.com/britter
