You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Benedikt Ritter <br...@apache.org> on 2013/12/24 09:51:51 UTC
[LANG] Document API breakage in FastDateFormat in JavaDoc?
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.
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
Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Posted by Benedikt Ritter <br...@apache.org>.
2013/12/24 sebb <se...@gmail.com>
> On 24 December 2013 08:51, Benedikt Ritter <br...@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
Re: [LANG] Document API breakage in FastDateFormat in JavaDoc?
Posted by sebb <se...@gmail.com>.
On 24 December 2013 08:51, Benedikt Ritter <br...@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.
> 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