[Pandas-dev] whatsnew vs release notes

[Joris Van den Bossche]

So to summarize the changes in the workflow:

- in PR's, only add entries in the relevant whatsnew file (no longer also
in release.rst). So we have only one place where all documentation on
changes, enhancements and bug fixes are gathered
- the entry in release.rst will then only updated before the release as the
announcement with a summary of whatsnew (highlights), etc

I adapted the wiki (
https://github.com/pydata/pandas/wiki/Documenting-new-features-and-bug-fixes)
and contributing.md to reflect this.

Allright?

Joris


2014-05-27 22:44 GMT+02:00 Jeff Reback <jeffreback at gmail.com>:

> well we are just going to have a link to the whatsnew in the announcement;
> it's much too long to actually include it in the mail; though planning on
> including the highlites (at the top will be directly listed)
>
> I think of whatsnew as all changes but with examples (as needed). the
> original idea behind release notes was that it was a list of issues fixed
> with very limited examples (or none)
>
> I would be +1 in only using the whatsnew and then maybe have links back to
> the major sections from the release notes. (the reason for keeping the
> release notes is that people expect to see them as they are standard parts
> of a project). so going forward only have to edit whatsnew.
>
> it just seems simpler to maintain a whatsnew for a particular version as a
> single file (as then no mistaking which section to put the notes in).
>
> I guess the reverse is in place now for the bug fixes (eg they live in
> release notes and ref from whatsnew)
>
> On May 27, 2014, at 10:35 AM, Joris Van den Bossche <
> jorisvandenbossche at gmail.com> wrote:
>
> Hi list,
>
> A question about the possible duplicative nature of the release notes and
> whatsnew page. I know this has been discussed earlier (eg
> https://github.com/pydata/pandas/issues/4389), and the conclusion there
> was "*Release notes has every change, with a small description and issue
> reference. Whatsnew has 'big' changes, and examples (if necessary), and is
> the 'announcement' email, while release notes is the reference doc*".
> This is also stated on the wiki (
> https://github.com/pydata/pandas/wiki/Documenting-new-features-and-bug-fixes
> ).
>
> But looking at the actual pages of the upcoming 0.14 release, I think
> almost everything in release notes is also in whatsnew, apart from the
> (long) bug fixes section, and that whatsnew has examples while release
> notes has not, and whatsnew is structured a bit more by topic.
> In addition, the whatsnew file has also become much to large to be
> appropriate as the 'announcement' but has become the reference doc in my
> regard.
>
> Seeing this duplication (and also a lot of PRs that just add the same
> sentence in both files), I was wondering if this is worth it. And if it
> would not be better (less work for the contributor, and also for a user
> looking at these pages on the website having both does not seem that
> usefull) to just have one extensive page with the two merged. And then
> before a release a summary with the most notable parts of that can be made
> to use as announcement?
>
> Regards,
> Joris
>
>
>
> _______________________________________________
> Pandas-dev mailing list
> Pandas-dev at python.org
> https://mail.python.org/mailman/listinfo/pandas-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/pandas-dev/attachments/20140531/dfac66cb/attachment.html>