Explain the news file format

python · brettcannon · Jun 23, 2017 · May 27, 2017 · May 27, 2017 · Jun 23, 2017
commit f35dce2a9d803d3b00b25ddb4328f5fd515256ac
diff --git a/committing.rst b/committing.rst
@@ -23,7 +23,7 @@ later in this document):
 #. Was ``configure`` regenerated (if necessary)?
 #. Was ``pyconfig.h.in`` regenerated (if necessary)?
 #. Was the submitter added to ``Misc/ACKS`` (as appropriate)?
-#. Was ``Misc/NEWS`` updated (as appropriate)?
+#. Was an entry added to ``Misc/NEWS.d`` (as appropriate)?
 #. Was "What's New" updated (as appropriate)?
 #. Were appropriate labels added to signify necessary backporting of the
    pull request?
@@ -32,7 +32,7 @@ later in this document):
    If you want to share your work-in-progress code on a feature or bugfix,
    either open a ``WIP``-prefixed PR, publish patches on the
    `issue tracker`_ or create a public fork of the repository.
-   
+
 .. _issue tracker: https://bugs.python.org
 
 
@@ -79,7 +79,7 @@ The automated patch checklist runs through:
   (using ``Tools/scripts/reindent-rst.py``)
 * Has the documentation been updated?
 * Has the test suite been updated?
-* Has ``Misc/NEWS`` been updated?
+* Has an entry in ``Misc/NEWS.d`` been added?
 * Has ``Misc/ACKS`` been updated?
 * Has ``configure`` been regenerated, if necessary?
 * Has ``pyconfig.h.in`` been regenerated, if necessary?
@@ -115,7 +115,7 @@ someone else. When doing so you will want to make sure of some things.
 First, make sure the patch is in a good state. Both :ref:`patch` and
 :ref:`helptriage`
 explain what is to be expected of a patch. Typically patches that get cleared by
-triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS``
+triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS.d``
 entries (which a core developer should make sure are updated appropriately).
 
 Second, make sure the patch does not break backwards-compatibility without a
@@ -127,12 +127,12 @@ is worth it, ask on python-dev.
 
 Third, ensure the patch is attributed correctly with the contributor's
 name in ``Misc/ACKS`` if they aren't already there (and didn't add themselves
-in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS`` entry
+in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS.d`` entry
 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
 original checkin message in that case).
 
 Finally, make sure that the submitter of the
@@ -171,17 +171,17 @@ for inclusion.
    http://www.python.org/psf/contrib/contrib-form/
 
 
-What's New and NEWS Entries
+What's New and News Entries
 ---------------------------
 
-Almost all changes made to the code base deserve an entry in ``Misc/NEWS``.
+Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``.
 If the change is particularly interesting for end users (e.g. new features,
 significant improvements, or backwards-incompatible changes), an entry in
 the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added
 as well.
 
 There are two notable exceptions to this general principle, and they
-both relate to changes that *already* have a NEWS entry, and have not yet
+both relate to changes that *already* have a news entry, and have not yet
 been included in any formal release (including alpha and beta releases).
 These exceptions are:
 
@@ -191,7 +191,7 @@ These exceptions are:
   then cut prior to the first beta).
 
 * If a change is a fix (or other adjustment) to an earlier unreleased change
-  and the original NEWS entry remains valid, then no additional entry is
+  and the original news entry remains valid, then no additional entry is
   needed.
 
 Needing a What's New entry almost always means that a change is *not*
@@ -201,25 +201,40 @@ when implemented, these changes *must* be noted in the "New Additions in
 Python 2.7 Maintenance Releases" section of the Python 2.7 What's New
 document.
 
-New NEWS entries are customarily added at or near the top of their
-respective sections, so that entries within a section appear in approximate
-order from newest to oldest.  However, this is customary and not a
-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.
+
+If you are unable to use the tool you can create the news entry file manually.
+The ``Misc/NEWS.d`` directory contains a sub-directory named ``next`` which
+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``:
+
+* ``<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
+unique across branches, e.g. ``Yl4gI2``
 
-The NEWS file is now read by Sphinx to produce the "Changelog" page; accordingly
-it should be valid reStructuredText.  The "default role" (single backticks) can
-be used to refer to objects in the documentation.  Example NEWS entry::
+So a file name may be
+``Misc/NEWS.d/next/Library/2017-05-27.bpo-12345.Yl4gI2.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
+width should be used. The "default role"
+(single backticks) in reST can be used to refer to objects in the documentation.
+Example news entry::
+
+  Fix warning message when `os.chdir()` fails inside
+  `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
 
 (In all other ``.rst`` files, the single backticks should not be used.  They are
 allowed here because NEWS is meant to be as readable as possible unprocessed.)
 
-A nice trick to make merging across branches work more smoothly is to
-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
+way of adding news entries, it is now no longer necessary thanks to ``blurb``
+and the use of individual files for each news entry. Only release managers
+should ever edit ``Misc/NEWS``.
 
 
 Commit Messages
@@ -235,10 +250,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.
-   
+
    Thanks to Monty Python for the patch.
 
 The first line or sentence is meant to be a dense, to-the-point explanation
@@ -272,7 +287,7 @@ Working with Git_
 
 .. seealso::
    :ref:`gitbootcamp`
-   
+
 As a core developer, the ability to push changes to the official Python
 repositories means you have to be more careful with your workflow:
 
@@ -282,10 +297,10 @@ repositories means you have to be more careful with your workflow:
   dedicated to maintenance of the work before the work gets integrated in the
   main repository.
 
-* You should not commit directly into the ``master`` branch, or any of the 
+* You should not commit directly into the ``master`` branch, or any of the
   maintenance branches (``2.7``, ``3.5``, or ``3.6``).  You should commit against
   your own feature branch, and create a pull request.
-  
+
 It is recommended to keep a fork of the main repository around, as it allows simple
 reversion of all local changes (even "committed" ones) if your local clone gets
 into a state you aren't happy with.
@@ -410,7 +425,7 @@ new features.  The other branches only receive bug fixes or security fixes.
 Backporting Changes to an Older Version
 ---------------------------------------
 
-When it is determined that a pull request needs to be backported into one or more of 
+When it is determined that a pull request needs to be backported into one or more of
 the maintenance branches, a core developer can apply the labels ``needs backport to X.Y``
 to the pull request.
 
@@ -421,13 +436,13 @@ on the ``master`` branch.  To display the 10 most recent commit hashes and their
 line of the commit message::
 
    git log -10 --oneline
-   
+
 Prefix the backport pull request with the branch, for example::
 
    [3.6] bpo-12345: Fix the Spam Module
-   
+
 Note that cherry_picker.py_ adds the branch prefix automatically.
-   
+
 Once the backport pull request has been created, remove the
 ``needs backport to X.Y`` label from the original pull request.  (Only Core
 Developers can apply labels to GitHub pull requests).