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
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@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@python.org https://mail.python.org/mailman/listinfo/pandas-dev
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@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@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@python.org https://mail.python.org/mailman/listinfo/pandas-dev
perfect thanks
On May 31, 2014, at 9:10 AM, Joris Van den Bossche <jorisvandenbossche@gmail.com> wrote:
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@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@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@python.org https://mail.python.org/mailman/listinfo/pandas-dev
participants (2)
-
Jeff Reback -
Joris Van den Bossche