From 4de8b6265e12384d12189a1682cee477e40edaaa Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Sat, 27 May 2017 15:18:51 -0700
Subject: [PATCH 1/9] Drop unnecessary mentions of Misc/NEWS

---
 developers.rst  | 10 +++++-----
 gitbootcamp.rst |  2 +-
 pullrequest.rst |  2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/developers.rst b/developers.rst
index 23926681e..63b741ea0 100644
--- a/developers.rst
+++ b/developers.rst
@@ -8,10 +8,10 @@ This file is a running log of developers given commit privileges for Python.
 The purpose is to provide some institutional memory of who was given access
 and why.
 
-The first entry starts in April 2005.  In keeping with the style of Misc/NEWS,
-newer entries should be added to the top.  Entries should include the name
-or initials of the project admin who made the change or granted access.  The
-procedure for adding or removing users is described in :ref:`altering-access`.
+The first entry starts in April 2005.  Newer entries should be added to the top.
+Entries should include the name or initials of the project admin who made the
+change or granted access.  The procedure for adding or removing users is
+described in :ref:`altering-access`.
 
 Note, when giving new commit permissions, be sure to get a contributor agreement
 from the committer.  See http://www.python.org/psf/contrib/ for details.  Commit
@@ -27,7 +27,7 @@ Permissions History
 
 - Carol Willing was given push privileges on May 24, 2017 by Brett Cannon,
   on his own recommendation.
-  
+
 - Mariatta Wijaya was given push privileges on January 27, 2017 by Brett Cannon,
   on the recommendation of Raymond Hettinger.
 
diff --git a/gitbootcamp.rst b/gitbootcamp.rst
index c5c5f7abd..9f3e4eba9 100644
--- a/gitbootcamp.rst
+++ b/gitbootcamp.rst
@@ -260,7 +260,7 @@ When a pull request submitter has enabled the `Allow edits from maintainers`_
 option, Python Core Developers may decide to make any remaining edits needed
 prior to merging themselves, rather than asking the submitter to do them. This
 can be particularly appropriate when the remaining changes are bookkeeping
-items like updating ``Misc/ACKS`` and ``Misc/NEWS``.
+items like updating ``Misc/ACKS``.
 
 .. _Allow edits from maintainers: https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/
 
diff --git a/pullrequest.rst b/pullrequest.rst
index 0289970bf..3b8e32e19 100644
--- a/pullrequest.rst
+++ b/pullrequest.rst
@@ -352,6 +352,6 @@ Crediting
 ---------
 
 Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most
-often, in a contribution's ``Misc/NEWS`` entry as well).  You may be
+often, in a contribution's news entry as well).  You may be
 asked to make these edits on the behalf of the core developer who
 accepts your pull request.

From f35dce2a9d803d3b00b25ddb4328f5fd515256ac Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Sat, 27 May 2017 15:18:59 -0700
Subject: [PATCH 2/9] Explain the news file format

---
 committing.rst | 79 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 47 insertions(+), 32 deletions(-)

diff --git a/committing.rst b/committing.rst
index 71053562b..ae6e36dae 100644
--- 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).

From d1a5981d810406f94d8d6f3f3f5aff9868c8e72e Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Thu, 22 Jun 2017 17:03:47 -0700
Subject: [PATCH 3/9] Fix a reST formatting error

---
 committing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/committing.rst b/committing.rst
index 52590e1d8..a2956598c 100644
--- a/committing.rst
+++ b/committing.rst
@@ -215,7 +215,7 @@ standard library). The file name itself should be of the format
 * ``<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``
+  unique across branches, e.g. ``Yl4gI2``
 
 So a file name may be
 ``Misc/NEWS.d/next/Library/2017-05-27.bpo-12345.Yl4gI2.rst``.

From c5b8bedb09d5f2d5b43b7d403cc87420518371b8 Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Thu, 22 Jun 2017 17:45:46 -0700
Subject: [PATCH 4/9] Make it more obvious Misc/NEWS.d is a directory

---
 committing.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/committing.rst b/committing.rst
index a2956598c..d878e3081 100644
--- 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 an entry added to ``Misc/NEWS.d`` (as appropriate)?
+#. Was an entry added under ``Misc/NEWS.d/next`` (as appropriate)?
 #. Was "What's New" updated (as appropriate)?
 #. Were appropriate labels added to signify necessary backporting of the
    pull request?
@@ -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 an entry in ``Misc/NEWS.d`` been added?
+* Has an entry under ``Misc/NEWS.d/next`` been added?
 * Has ``Misc/ACKS`` been updated?
 * Has ``configure`` been regenerated, if necessary?
 * Has ``pyconfig.h.in`` been regenerated, if necessary?

From 7d39139b4995d5026c85e43fbca4916323f5a615 Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Thu, 22 Jun 2017 17:47:02 -0700
Subject: [PATCH 5/9] Make the bpo- prefix more of a constant

---
 committing.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/committing.rst b/committing.rst
index d878e3081..5421a338a 100644
--- a/committing.rst
+++ b/committing.rst
@@ -210,10 +210,11 @@ 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>.bpo-<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``
+* ``<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``
 

From 1124486d63f1620902bf4416ac3ae876e036e99a Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Thu, 22 Jun 2017 18:08:26 -0700
Subject: [PATCH 6/9] Clarify some details

---
 committing.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/committing.rst b/committing.rst
index 5421a338a..15d23aa2d 100644
--- a/committing.rst
+++ b/committing.rst
@@ -221,10 +221,11 @@ standard library). The file name itself should be of the format
 So a file name may be
 ``Misc/NEWS.d/next/Library/2017-05-27.bpo-12345.Yl4gI2.rst``.
 
-A news file contents should be valid reStructuredText. An 80 character column
-width should be used. The "default role"
+The contents of a news file should be valid reStructuredText. The "default role"
 (single backticks) in reST can be used to refer to objects in the documentation.
-Example news entry::
+An 80 character column width should be used. There is no indentation or leading
+marker in the file (e.g. ``-``). There is also no need to start the entry with
+the issue number as it's part of the file name itself. Example news entry::
 
   Fix warning message when `os.chdir()` fails inside
   `test.support.temp_cwd()`.  Patch by Chris Jerdonek.

From 0b18b6bc70d43770767868fbf4e5864d39f84363 Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Thu, 22 Jun 2017 18:12:30 -0700
Subject: [PATCH 7/9] Don't even mention Misc/NEWS

---
 committing.rst | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/committing.rst b/committing.rst
index 15d23aa2d..5813c3a54 100644
--- a/committing.rst
+++ b/committing.rst
@@ -230,13 +230,9 @@ the issue number as it's part of the file name itself. 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.)
-
-**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``.
+(In other ``.rst`` files the single backticks should not be used.  They are
+allowed here because news entries are meant to be as readable as possible
+unprocessed.)
 
 
 Commit Messages
@@ -247,9 +243,10 @@ communicate that reason to other core developers. Python core developers have
 developed a standard way of formatting commit messages that everyone is
 expected to follow.
 
-Our usual convention mimics that used in the ``Misc/NEWS`` file.  Actually,
-it is common to simply paste the NEWS entry into the commit message.  Here
-is an example::
+Our usual convention mimics that used in news entries (it is actually common to
+start by pasting the news entry into the commit message). The only key
+difference when compared to a news entry is the inclusion of the issue number
+as the beginning of the commit message. Here is an example::
 
    bpo-42: the spam module is now more spammy.
 

From b5cf357f5ebc9268faa2c1b0eacc316ff09c89c0 Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Fri, 23 Jun 2017 09:53:29 -0700
Subject: [PATCH 8/9] Fix "checkin" misspelling

---
 committing.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/committing.rst b/committing.rst
index 5813c3a54..37eea2151 100644
--- a/committing.rst
+++ b/committing.rst
@@ -128,12 +128,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.d`` entry
-and the checkin message. If the patch has been heavily modified then "Initial
+and the check-in 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.d`` in a subsequent checkin (don't worry about trying to fix the
-original checkin message in that case).
+If you omit correct attribution in the initial check-in, then update ``ACKS``
+and ``NEWS.d`` in a subsequent check-in (don't worry about trying to fix the
+original check-in message in that case).
 
 Finally, make sure that the submitter of the
 patch has a CLA in place (indicated by an asterisk following their username

From 4f3b947b9d011c236f15b35be3cfbe8ddd21264b Mon Sep 17 00:00:00 2001
From: Brett Cannon <brett@python.org>
Date: Fri, 23 Jun 2017 09:57:31 -0700
Subject: [PATCH 9/9] Clarify the requirements of the nonce

---
 committing.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/committing.rst b/committing.rst
index 37eea2151..a90d11c18 100644
--- a/committing.rst
+++ b/committing.rst
@@ -215,8 +215,10 @@ standard library). The file name itself should be of the format
 * ``<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. ``12345``
   for ``bpo-12345``
-* ``<nonce>`` is a unique, six-character string to guarantee the file name is
-  unique across branches, e.g. ``Yl4gI2``
+* ``<nonce>`` is some "unique" string to guarantee the file name is
+  unique across branches, e.g. ``Yl4gI2`` (typically six characters, but it can
+  be any length of letters and numbers, and its uniqueness can be satisfied by
+  typing random characters on your keyboard)
 
 So a file name may be
 ``Misc/NEWS.d/next/Library/2017-05-27.bpo-12345.Yl4gI2.rst``.