From 84d26327d09947b2549359cdde270830833b9632 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 11:35:27 +0100 Subject: [PATCH 1/7] Rework the docs for NEWS/What's New entries --- core-developers/committing.rst | 56 +++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 8b3ee2b3cc..f13d50a886 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -80,21 +80,14 @@ 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 entail NEWS entries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. There are two notable exceptions to this general principle, and they -both relate to changes that: - -* Already have a ``NEWS`` entry -* Have not yet been included in any formal release (including alpha - and beta releases) - -These are the two exceptions: +both relate to changes that already have a ``NEWS`` entry, +or changes that have not yet been included in any formal release +(including alpha and beta releases): #. **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 +98,27 @@ 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. +Other changes that generally do not require ``NEWS`` entries are documentation changes, +test changes, and strictly internal changes with no user-visible effects. + +Changes that entail 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), an entry in +the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added +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 `_, @@ -132,6 +144,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 actuall 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 +169,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 `. -While Sphinx roles can be beneficial to readers, they are not required. -Inline ````code blocks```` can be used instead. - Working with Git_ ----------------- From 4def01c53b0babc160c200bc8c3497dd95af0ad0 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 15:41:24 +0100 Subject: [PATCH 2/7] Address most of Ezio's review remarks --- core-developers/committing.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index f13d50a886..8d5e2d413c 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -80,8 +80,8 @@ to enter the public source tree. Ask yourself the following questions: Updating NEWS and What's New in Python -------------------------------------- -Changes that entail NEWS entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Changes that require NEWS entries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. There are two notable exceptions to this general principle, and they @@ -101,12 +101,12 @@ or changes that have not yet been included in any formal release Other changes that generally do not require ``NEWS`` entries are documentation changes, test changes, and strictly internal changes with no user-visible effects. -Changes that entail What's New in Python entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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), an entry in -the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added +the ``What's New in Python`` document (in :cpy-file:`Doc/whatsnew/`) should be added in addition to the ``NEWS`` entry. In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry @@ -153,7 +153,7 @@ 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 actuall diff for the change. +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 From 7464097f642c3389f6535986078b4b1eca1f9872 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 17:51:02 +0100 Subject: [PATCH 3/7] Address review: improve wording wrt. exceptions --- core-developers/committing.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 8d5e2d413c..4e11ed5eb8 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -83,11 +83,17 @@ Updating NEWS and What's New in Python Changes that require NEWS entries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. -There are two notable exceptions to this general principle, and they -both relate to changes that already have a ``NEWS`` entry, -or changes that have not yet been included in any formal release -(including alpha and beta releases): +Most changes made to the code base deserve an entry in :cpy-file:`Misc/NEWS.d`, +except for the following: + +* documentation changes in general +* test changes in general +* strictly internal changes with no user-visible effects +* changes that already have a ``NEWS`` entry +* changes that have not yet been included in any formal release + (including alpha and beta releases) + +For the latter two exceptions, 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 From d9067abe88b7b9393b336a657b3eaa6ae498d55e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 18:15:05 +0100 Subject: [PATCH 4/7] Apply suggestions from Hugo's review Co-authored-by: Hugo van Kemenade --- core-developers/committing.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 8d5e2d413c..2e24f57be3 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -83,7 +83,7 @@ Updating NEWS and What's New in Python Changes that require NEWS entries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. +Almost all changes made to the codebase deserve an entry in ``Misc/NEWS.d``. There are two notable exceptions to this general principle, and they both relate to changes that already have a ``NEWS`` entry, or changes that have not yet been included in any formal release @@ -105,16 +105,16 @@ 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), an entry in -the ``What's New in Python`` document (in :cpy-file:`Doc/whatsnew/`) should be added +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. +in the "What's New in Python" entry. .. note:: - A change that needs an entry in ``What's New in Python``, + 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 From ce39b801e4da3cbf57099c6299c4ace06dd48293 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 20:37:58 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Hugo van Kemenade --- core-developers/committing.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index ddd21dde70..c73addd6f9 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -86,14 +86,14 @@ Changes that require NEWS entries Most changes made to the code base deserve an entry in :cpy-file:`Misc/NEWS.d`, except for the following: -* documentation changes in general -* test changes in general +* documentation changes +* test changes * strictly internal changes with no user-visible effects * changes that already have a ``NEWS`` entry * changes that have not yet been included in any formal release (including alpha and beta releases) -For the latter two exceptions, note the following: +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 @@ -104,9 +104,6 @@ For the latter two exceptions, note the following: change and the original** ``NEWS`` **entry remains valid**, then no additional entry is needed. -Other changes that generally do not require ``NEWS`` entries are documentation changes, -test changes, and strictly internal changes with no user-visible effects. - Changes that require "What's New in Python" entries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 0604f8eceb355a16dd9d752b42470b5cbb56271b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 21:45:52 +0100 Subject: [PATCH 6/7] all your base Co-authored-by: Hugo van Kemenade --- core-developers/committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 11c5e32c80..73ebf256af 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -83,7 +83,7 @@ Updating NEWS and What's New in Python Changes that require NEWS entries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Most changes made to the code base deserve an entry in :cpy-file:`Misc/NEWS.d`, +Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, except for the following: * documentation changes From d371fc4221eb3c5ab225ceb3bd9b1a7d7c558ca7 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Dec 2023 21:47:56 +0100 Subject: [PATCH 7/7] the revert Co-authored-by: Hugo van Kemenade --- core-developers/committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 73ebf256af..3b2a103026 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -90,7 +90,7 @@ except for the following: * test changes * strictly internal changes with no user-visible effects * changes that already have a ``NEWS`` entry -* changes that have not yet been included in any formal release +* reverts that have not yet been included in any formal release (including alpha and beta releases) For the last two, note the following: