commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Date Sat, 28 Dec 2013 15:58:25 GMT
On Sat, Dec 28, 2013 at 10:13 AM, Benedikt Ritter <britter@apache.org>wrote:

> 2013/12/27 Gary Gregory <garydgregory@gmail.com>
>
> > 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 ,ggregory@apache.org
> > Subject: Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
> >
> >
> >
> >
> > 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
> >
>
>
>
> --
> http://people.apache.org/~britter/
> http://www.systemoutprintln.de/
> http://twitter.com/BenediktRitter
> http://github.com/britter
>



-- 
E-Mail: garydgregory@gmail.com | ggregory@apache.org
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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message