Rework the docs for NEWS/What's New entries (#1238)

- Add links to CPython repo where appropriate
- Add some information about how to word NEWS entries
- Break up in subsubsections instead of keeping all the text in a single large subsection
- Mention that test, docs, and strictly internal changes seldom require NEWS entries
- Use more appropriate markup iso. double backticks

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>

Author: 4 people

core-developers/committing.rst

@@ -80,21 +80,20 @@ to enter the public source tree. Ask yourself the following questions:
 Updating NEWS and What's New in Python
 --------------------------------------
 
-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), then an entry in
-the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added
-as well. Changes that affect documentation only generally do not require
-a ``NEWS`` entry.
+Changes that require NEWS entries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are two notable exceptions to this general principle, and they
-both relate to changes that:
+Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`,
+except for the following:
 
-* Already have a ``NEWS`` entry
-* Have not yet been included in any formal release (including alpha
-  and beta releases)
+* documentation changes
+* test changes
+* strictly internal changes with no user-visible effects
+* changes that already have a ``NEWS`` entry
+* reverts that have not yet been included in any formal release
+  (including alpha and beta releases)
 
-These are the two exceptions:
+For the last two, note the following:
 
 #. **If a change is reverted prior to release**, then the corresponding
    entry is simply removed. Otherwise, a new entry must be added noting
@@ -105,8 +104,24 @@ These are the two exceptions:
    change and the original** ``NEWS`` **entry remains valid**, then no additional
    entry is needed.
 
-If a change needs an entry in ``What's New in Python``, then it is very
-likely not suitable for including in a maintenance release.
+Changes that require "What's New in Python" entries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a change is particularly interesting for end users (e.g. new features,
+significant improvements, or backwards-incompatible changes), add an entry in
+the "What's New in Python" document (in :cpy-file:`Doc/whatsnew/`)
+in addition to the ``NEWS`` entry.
+
+In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry
+in the "What's New in Python" entry.
+
+.. note::
+
+    A change that needs an entry in "What's New in Python",
+    is very likely not suitable for inclusion in a maintenance release.
+
+How to add a NEWS entry
+^^^^^^^^^^^^^^^^^^^^^^^
 
 ``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The
 ``NEWS`` entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`_,
@@ -132,6 +147,17 @@ to the standard library). The file name itself should be in the format
 As a result, a file name can look something like
 ``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.gh-issue-12345.Yl4gI2.rst``.
 
+How to write a NEWS entry
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All ``NEWS`` entries end up being part of the changelog.
+The changelog contains *a lot* of entries,
+and its intended audience is mainly users, not core devs and contributors.
+Take this into consideration when wording your ``NEWS`` entry.
+Describe the user-visible effects of your change succinctly and accurately;
+avoid long technical elaborations, digressions, and do not expect or require
+the reader to have read the actual diff for the change.
+
 The contents of a ``NEWS`` file should be valid reStructuredText. 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
@@ -146,9 +172,6 @@ The inline Sphinx roles like ``:func:`` can be used help readers
 find more information. You can build HTML and verify that the
 link target is appropriate by using :ref:`make html <building-using-make>`.
 
-While Sphinx roles can be beneficial to readers, they are not required.
-Inline ````code blocks```` can be used instead.
-
 
 Working with Git_
 -----------------