commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benedikt Ritter <brit...@apache.org>
Subject Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Date Fri, 27 Dec 2013 12:51:33 GMT
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