On Sat, Dec 28, 2013 at 10:13 AM, Benedikt Ritter <[email protected]>wrote:
> 2013/12/27 Gary Gregory <[email protected]> > > > 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. > > > > Sorry, you lost me there... Haven't we always treated public types and > methods like this? > Sorry, wrong thread. Please ignore. Gary > > Benedikt > > > > > > Gary > > > > > > -------- Original message -------- > > From: Benedikt Ritter > > Date:12/27/2013 07:51 (GMT-05:00) > > To: Commons Developers List ,[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 > > > > > > -- > http://people.apache.org/~britter/ > http://www.systemoutprintln.de/ > http://twitter.com/BenediktRitter > http://github.com/britter > -- E-Mail: [email protected] | [email protected] Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
