Document the news file format #212

brettcannon · 2017-05-27T22:22:09Z

This should not be merged until larryhastings/blurb relocates to python/core-workflow, python/cpython is updated appropriately, and python/core-workflow#66 is closed.

…blurb

larryhastings · 2017-06-23T00:44:07Z

committing.rst

+itself contains various sub-directories representing classifications for what
+was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the
+standard library). The file name itself should be of the format
+``<date>.<issue-number>.<nonce>.rst``:


Format is <date>.bpo-<issue-number>.<nonce>.rst. The fields between and are theoretically tagged, so we can add more metadata later as needed.

Oh, I guess below you suggest that "bpo-" is considered part of the issue number? That kind of suggests we'd have other things there besides bpo-, which right now I don't think blurb would permit. It certainly wouldn't emit it.

Clarified in the latest commit.

larryhastings

Some feedback.

larryhastings · 2017-06-23T00:46:16Z

committing.rst

+standard library). The file name itself should be of the format
+``<date>.<issue-number>.<nonce>.rst``:
+
+* ``<date>`` is today's date in ``YYYY-MM-DD`` format, e.g. ``2017-05-27``


I actually emit YYYY-MM-DD-HH-MM-SS, both to further prevent collisions, and to ensure that entries are added in strict chronological order. It doesn't make a big difference, but I'd like it if you mentioned it. Changing the line to

<date> is today's date in YYYY-MM-DD or YYYY-MM-DD-HH-MM-DD format, e.g. 2017-05-27or 2017-05-27-08-22-35

larryhastings · 2017-06-23T00:47:06Z

committing.rst

+itself contains various sub-directories representing classifications for what
+was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the
+standard library). The file name itself should be of the format
+``<date>.<issue-number>.<nonce>.rst``:


Oh, I guess below you suggest that "bpo-" is considered part of the issue number? That kind of suggests we'd have other things there besides bpo-, which right now I don't think blurb would permit. It certainly wouldn't emit it.

larryhastings · 2017-06-23T00:48:02Z

committing.rst

+
+* ``<date>`` is today's date in ``YYYY-MM-DD`` format, e.g. ``2017-05-27``
+* ``<issue-number>`` is the issue number the change is for, e.g. ``bpo-12345``
+* ``<nonce>`` is a unique, six-character string to guarantee the file name is


There's no length requirement for the nonce. I think even a zero-character string would work.

larryhastings · 2017-06-23T00:48:47Z

committing.rst

-put a new entry after the first or first two entries rather than at the very
-top.  This way if you commit, pull new changesets and merge, the merge will
-succeed automatically.
+**No editing should be  done to ``Misc/NEWS``**. While this was the traditional


Actually, we decided to remove Misc/NEWS from the CPython tree. It'll be generated just-in-time as part of the release process so tarballs look the same. But it should no longer be checked in.

I dropped the mention.

larryhastings · 2017-06-23T00:49:50Z

committing.rst


-   - bpo-15304: Fix warning message when `os.chdir()` fails inside
-     `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
+A news file contents should be valid reStructuredText. An 80 character column


Bad English. Better: "The contents of a news file should be [...]"

larryhastings · 2017-06-23T00:50:47Z

committing.rst

+A news file contents should be valid reStructuredText. An 80 character column
+width should be used. The "default role"
+(single backticks) in reST can be used to refer to objects in the documentation.
+Example news entry::


I'd also like this to mention that, unlike in Misc/NEWS, news entries in Misc/NEWS.d shouldn't start with a -, shouldn't indent subsequent lines, and shouldn't start with Issue # or bpo-.

I was wondering about that ;-)

terryjreedy · 2017-06-23T01:06:31Z

committing.rst

-requirement.
+News entries go into the ``Misc/NEWS.d`` directory as individual files. The
+easiest way to create a news entry is to use the
+`blurb <https://pypi.org/project/blurb/>`_ tool and its ``blurb add`` command.


Will blurb add open some editor or editing window?

I believe it will open an editor, yes.

It opens $EDITOR.

If $EDITOR isn't set, it will try a sane default on some platforms ("notepad" on Windows, /etc/alternatives/editor on Linux (if present)). I think when Ned got it working on macOS he said it shouldn't try to guess on that platform.

Notepad is definitely lightweight, and for a typical news item, should be fine.

If the editor is not set on macOS, it seems reasonable to default to TextEdit which is what the operating system does.

This level of discussion is more appropriate in the core-workflow issue tracker.

terryjreedy · 2017-06-23T01:07:59Z

committing.rst

+* ``<issue-number>`` is the issue number the change is for, e.g. ``12345``
+  for ``bpo-12345``
+* ``<nonce>`` is a unique, six-character string to guarantee the file name is
+  unique across branches, e.g. ``Yl4gI2``


This seems like a problem for hand written files. Will the nonce remain the same in backported files? (I can take 'unique across branches' either way.)

How so? Just randomly bang on your keyboard and keep 6 letters. 😄

Or any number of letters, even zero. The nonce is really just there as a final arbiter to prevent filename collisions.

I've now clarified this.

terryjreedy · 2017-06-23T01:08:40Z

committing.rst


-   - bpo-15304: Fix warning message when `os.chdir()` fails inside
-     `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
+A news file contents should be valid reStructuredText. An 80 character column


terryjreedy · 2017-06-23T01:11:53Z

committing.rst

-     `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
+A news file contents should be valid reStructuredText. An 80 character column
+width should be used. The "default role"
+(single backticks) in reST can be used to refer to objects in the documentation.


Will they be ignored if there is no corresponding object in the docs?

terryjreedy · 2017-06-23T01:13:53Z

committing.rst

@@ -235,10 +251,10 @@ it is common to simply paste the NEWS entry into the commit message.  Here
 is an example::

   bpo-42: the spam module is now more spammy.


This contradicts Larry's comment above about not starting with 'bpo' or issue number.

This is part of reST markup for a block literal so it actually doesn't when viewed as rendered HTML.

terryjreedy · 2017-06-23T01:16:52Z

committing.rst

   The spam module sporadically came up short on spam. This change
   raises the amount of spam in the module by making it more spammy.
-   
+


I have never added spaces before acknowledgements before and I believe same was generally true. Unless the resulting News/changelog is formatted differently from before, blank lines might make it harder, not easier to read.

If you mean the indent, that's once again because it's reST formatting for a literal block. If you mean the newline then I personally have always used it.

Regardless, I didn't change this format and so if you want to discuss the formatting of commit messages that belongs in a separate issue.

willingc · 2017-06-23T14:54:38Z

committing.rst

 and the checkin message. If the patch has been heavily modified then "Initial
 patch by <x>" is an appropriate alternate wording.

 If you omit correct attribution in the initial checkin, then update ``ACKS``
-and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the
+and ``NEWS.d`` in a subsequent checkin (don't worry about trying to fix the


Generally accepted usage is "check-in" for a noun or adjective or "check in" for a verb. No need to update for this PR as it's "checkin" throughout the document. Future revisions should probably correct this.

You can't point that out to the son of a former school teacher who almost had a minor in English and expect them not to fix it immediately. 😉

brettcannon · 2017-06-23T17:15:12Z

Thanks for all the feedback, everyone!

brettcannon added 2 commits May 27, 2017 15:18

Drop unnecessary mentions of Misc/NEWS

4de8b62

Explain the news file format

f35dce2

brettcannon requested a review from larryhastings May 27, 2017 22:22

the-knights-who-say-ni added the CLA signed label May 27, 2017

brettcannon added 2 commits June 22, 2017 17:01

Merge branch 'master' of https://github.com/python/devguide into use-…

c4eab76

…blurb

Fix a reST formatting error

d1a5981

brettcannon changed the title ~~[WIP] Document the news file format~~ Document the news file format Jun 23, 2017

larryhastings reviewed Jun 23, 2017

View reviewed changes

brettcannon added 2 commits June 22, 2017 17:45

Make it more obvious Misc/NEWS.d is a directory

c5b8bed

Make the bpo- prefix more of a constant

7d39139

larryhastings reviewed Jun 23, 2017

View reviewed changes

brettcannon added 2 commits June 22, 2017 18:08

Clarify some details

1124486

Don't even mention Misc/NEWS

0b18b6b

terryjreedy reviewed Jun 23, 2017

View reviewed changes

willingc reviewed Jun 23, 2017

View reviewed changes

brettcannon added 2 commits June 23, 2017 09:53

Fix "checkin" misspelling

b5cf357

Clarify the requirements of the nonce

4f3b947

brettcannon merged commit daaa4b5 into python:master Jun 23, 2017

brettcannon deleted the use-blurb branch June 23, 2017 17:14

AA-Turner pushed a commit to AA-Turner/devguide that referenced this pull request Jun 17, 2022

Document the news file format (python#212)

ef14d1e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the news file format #212

Document the news file format #212

brettcannon commented May 27, 2017

larryhastings Jun 23, 2017

larryhastings Jun 23, 2017

brettcannon Jun 23, 2017

larryhastings left a comment

larryhastings Jun 23, 2017

larryhastings Jun 23, 2017

larryhastings Jun 23, 2017

larryhastings Jun 23, 2017

brettcannon Jun 23, 2017

larryhastings Jun 23, 2017

brettcannon Jun 23, 2017

terryjreedy Jun 23, 2017

larryhastings Jun 23, 2017

terryjreedy Jun 23, 2017

brettcannon Jun 23, 2017

terryjreedy Jun 23, 2017

brettcannon Jun 23, 2017

larryhastings Jun 23, 2017

terryjreedy Jun 23, 2017

willingc Jun 23, 2017

brettcannon Jun 23, 2017

terryjreedy Jun 23, 2017

brettcannon Jun 23, 2017

larryhastings Jun 23, 2017

brettcannon Jun 23, 2017

terryjreedy Jun 23, 2017

terryjreedy Jun 23, 2017

terryjreedy Jun 23, 2017

brettcannon Jun 23, 2017

terryjreedy Jun 23, 2017

brettcannon Jun 23, 2017

willingc Jun 23, 2017

brettcannon Jun 23, 2017

brettcannon commented Jun 23, 2017

		@@ -235,10 +251,10 @@ it is common to simply paste the NEWS entry into the commit message. Here
		is an example::

		bpo-42: the spam module is now more spammy.

		The spam module sporadically came up short on spam. This change
		raises the amount of spam in the module by making it more spammy.

Document the news file format #212

Document the news file format #212

Conversation

brettcannon commented May 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

larryhastings left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brettcannon commented Jun 23, 2017