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? 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
