Adding some concrete examples to the NEWS entry guide?

While the lack of conflicts with the new snippet based NEWS entries is excellent, I've noticed something I didn't even realise I was previously relying on: when adding a new NEWS entry, I don't have any example entries to look at the way I did when I was editing Misc/NEWS directly.
With the move to conflict-free NEWS, we should probably also move https://devguide.python.org/committing/#what-s-new-and-news-entries out of the committers' section and make it a section under https://devguide.python.org/pullrequest/ instead.
So what I'm thinking we could do is:
- add some concrete examples for a few different kinds of changes (e.g. bug fix, feature addition, significant internal refactoring) - add those examples to the end of the blurb entry template as comments - migrate most of the existing What's New & NEWS content into the PR guide, and change the "Accepting a PR" section to be about deciding whether or not those entries are needed

+1.
Related question: Should the news entry include "Patch by <name>?". I noticed some entries have this, some don't. Is there a rule?
Thanks.

"Patch by" was useful with Mercurial which didn't allow to store an author and a committer. Git now stores the author and the committer:
vstinner@apu$ git show --pretty=full 5b48dc638b7405fd9bde4d854bf477dfeaaddf44 --stat commit 5b48dc638b7405fd9bde4d854bf477dfeaaddf44 Author: Jonas Haag jonas@lophus.org Commit: Antoine Pitrou pitrou@free.fr
I'm not sure about added *manually* the author in the NEWS entry. I would prefer to have a generated page like https://thanks.rust-lang.org/ to limit the work of the reviewer (and of the author).
My intent is not to hide the author of a contributor, but make contributions as simple as possible in Python, and to better "scale" our workflow.
What do you think?
Victor
2017-11-26 17:08 GMT+01:00 Mariatta Wijaya mariatta.wijaya@gmail.com:
+1.
Related question: Should the news entry include "Patch by <name>?". I noticed some entries have this, some don't. Is there a rule?
Thanks.
core-workflow mailing list -- core-workflow@python.org To unsubscribe send an email to core-workflow-leave@python.org https://mail.python.org/mm3/mailman3/lists/core-workflow.python.org/ This list is governed by the PSF Code of Conduct: https://www.python.org/psf/codeofconduct

On Mon, Nov 27, 2017 at 2:10 PM, Victor Stinner victor.stinner@gmail.com wrote:
"Patch by" was useful with Mercurial which didn't allow to store an author and a committer. Git now stores the author and the committer:
vstinner@apu$ git show --pretty=full 5b48dc638b7405fd9bde4d854bf477dfeaaddf44 --stat commit 5b48dc638b7405fd9bde4d854bf477dfeaaddf44 Author: Jonas Haag jonas@lophus.org Commit: Antoine Pitrou pitrou@free.fr
I'm not sure about added *manually* the author in the NEWS entry. I would prefer to have a generated page like https://thanks.rust-lang.org/ to limit the work of the reviewer (and of the author).
thanks.rust-lang.org basically dumps all author names without giving zero context. Contributor A might just a fix a typo or contribute a non-trivial feature. There is no way to figure it out without doing some research.
Instead, everyone who reads our changelog at https://docs.python.org/3/whatsnew/changelog.html can see what Contributor A exactly contributed to Python.
"Patch by" marker is already documented at https://devguide.python.org/committing/#what-s-new-and-news-entries and it's not hard to ask the contributor to add it. I usually add it myself in less than a minute.
--Berker

2017-11-27 16:29 GMT+01:00 Berker Peksağ berker.peksag@gmail.com:
thanks.rust-lang.org basically dumps all author names without giving zero context. Contributor A might just a fix a typo or contribute a non-trivial feature. There is no way to figure it out without doing some research.
Instead, everyone who reads our changelog at https://docs.python.org/3/whatsnew/changelog.html can see what Contributor A exactly contributed to Python.
Right. So we should keep it :-)
"Patch by" marker is already documented at https://devguide.python.org/committing/#what-s-new-and-news-entries and it's not hard to ask the contributor to add it. I usually add it myself in less than a minute.
I'm ok to ask the author to add himself/herself ;-)
Victor
participants (4)
-
Berker Peksağ
-
Mariatta Wijaya
-
Nick Coghlan
-
Victor Stinner