[Pandas-dev] whatsnew vs release notes

[Jeff Reback]

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/20140527/aa9b6664/attachment.html>