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. > 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]
