From 3e489a60ebe0da6d4c8fa571df6769a62d2ef912 Mon Sep 17 00:00:00 2001 From: stan Date: Mon, 3 Feb 2025 17:15:34 +0000 Subject: [PATCH 1/6] Move _what-s-new-and-news-entries to pull-request-lifecycle --- core-developers/committing.rst | 99 +--------------------- getting-started/pull-request-lifecycle.rst | 97 +++++++++++++++++++++ 2 files changed, 98 insertions(+), 98 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 326578c0b3..dca85a4160 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -72,104 +72,7 @@ to enter the public source tree. Ask yourself the following questions: 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 only documentation generally do not - require a ``NEWS`` entry. (See the following section for more information.) - -.. _news-entry: -.. _what-s-new-and-news-entries: - -Updating NEWS and What's New in Python --------------------------------------- - -Changes that require NEWS entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, -except for the following: - -* 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) - -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 - that the change has been reverted (for example, when a feature is released in - an alpha and 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 needed. - -Changes that require "What's New in Python" entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If a change is particularly interesting for end users (for example, 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 `_, -or the :pypi:`blurb` tool and its ``blurb add`` command. - -If you are unable to use the tool, then you can create the ``NEWS`` entry file -manually. The ``Misc/NEWS.d`` directory contains a sub-directory named -``next``, which contains various sub-directories representing classifications -for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating -to the standard library). The file name itself should be in the format -``.gh-issue-..rst``: - -* ```` is today's date joined with a hyphen (``-``) to your current - local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). -* ```` is the issue number the change is for (for example, ``12345`` - for ``gh-issue-12345``). -* ```` is a unique string to guarantee that the file name is - unique across branches (for example, ``Yl4gI2``). It is typically six characters - long, but it can be any length of letters and numbers. Its uniqueness - can be satisfied by typing random characters on your keyboard. - -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 (for example, ``-``). There is also no need to start the entry with the issue -number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a ``NEWS`` -entry:: - - Fix warning message when :func:`os.chdir` fails inside - :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. - -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 `. + require a ``NEWS`` entry. (See :ref:`_what-s-new-and-news-entries`.) Working with Git_ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 59242f13f0..0c5bd7bb79 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -237,6 +237,103 @@ should do to help ensure that your pull request is accepted. #. Proper :ref:`documentation ` additions/changes should be included. +.. _news-entry: +.. _what-s-new-and-news-entries: + +Updating NEWS and What's New in Python +-------------------------------------- + +Changes that require NEWS entries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, +except for the following: + +* 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) + +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 + that the change has been reverted (for example, when a feature is released in + an alpha and 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 needed. + +Changes that require "What's New in Python" entries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a change is particularly interesting for end users (for example, 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 `_, +or the :pypi:`blurb` tool and its ``blurb add`` command. + +If you are unable to use the tool, then you can create the ``NEWS`` entry file +manually. The ``Misc/NEWS.d`` directory contains a sub-directory named +``next``, which contains various sub-directories representing classifications +for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating +to the standard library). The file name itself should be in the format +``.gh-issue-..rst``: + +* ```` is today's date joined with a hyphen (``-``) to your current + local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). +* ```` is the issue number the change is for (for example, ``12345`` + for ``gh-issue-12345``). +* ```` is a unique string to guarantee that the file name is + unique across branches (for example, ``Yl4gI2``). It is typically six characters + long, but it can be any length of letters and numbers. Its uniqueness + can be satisfied by typing random characters on your keyboard. + +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 (for example, ``-``). There is also no need to start the entry with the issue +number since it is part of the file name. You can use +:ref:`inline markups ` too. Here is an example of a ``NEWS`` +entry:: + + Fix warning message when :func:`os.chdir` fails inside + :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. + +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 `. + Copyrights ========== From 68600132d6bdd7db084992383499b3f74a707c59 Mon Sep 17 00:00:00 2001 From: stan Date: Mon, 3 Feb 2025 17:19:21 +0000 Subject: [PATCH 2/6] Change to seealso --- core-developers/committing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index dca85a4160..e69734f99c 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -68,6 +68,10 @@ to enter the public source tree. Ask yourself the following questions: process, write to contributors@python.org. * **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** + + .. seealso:: + :ref:`what-s-new-and-news-entries` + If the change is particularly interesting for end users (for example, new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From dffca017c123ad1d477f23a7b55468310a3e2949 Mon Sep 17 00:00:00 2001 From: stan Date: Mon, 3 Feb 2025 17:20:58 +0000 Subject: [PATCH 3/6] Revert seealso This reverts commit 68600132d6bdd7db084992383499b3f74a707c59. --- core-developers/committing.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index e69734f99c..c2c6d3c772 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -68,15 +68,11 @@ to enter the public source tree. Ask yourself the following questions: process, write to contributors@python.org. * **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** - - .. seealso:: - :ref:`what-s-new-and-news-entries` - If the change is particularly interesting for end users (for example, 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 only documentation generally do not - require a ``NEWS`` entry. (See :ref:`_what-s-new-and-news-entries`.) + require a ``NEWS`` entry. (See :ref:`what-s-new-and-news-entries`) Working with Git_ From fbd50f05d45b783fce1497c323111439ec4ebdfc Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Mon, 3 Feb 2025 20:48:22 +0000 Subject: [PATCH 4/6] Update core-developers/committing.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- 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 c2c6d3c772..c39f8a779c 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -72,7 +72,7 @@ to enter the public source tree. Ask yourself the following questions: 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 only documentation generally do not - require a ``NEWS`` entry. (See :ref:`what-s-new-and-news-entries`) + require a ``NEWS`` entry. (See :ref:`what-s-new-and-news-entries`.) Working with Git_ From 44024a1dba85e7f9752e1854d84584bf53b9c544 Mon Sep 17 00:00:00 2001 From: stan Date: Mon, 3 Feb 2025 20:50:20 +0000 Subject: [PATCH 5/6] seealso works now? --- core-developers/committing.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index c2c6d3c772..4d0282d413 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -72,7 +72,10 @@ to enter the public source tree. Ask yourself the following questions: 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 only documentation generally do not - require a ``NEWS`` entry. (See :ref:`what-s-new-and-news-entries`) + require a ``NEWS`` entry. + + .. seealso:: + :ref:`what-s-new-and-news-entries` Working with Git_ From 6f6fbaeb6df2bd439242b59b9536ed611644cde7 Mon Sep 17 00:00:00 2001 From: stan Date: Mon, 3 Feb 2025 20:56:23 +0000 Subject: [PATCH 6/6] Change title levels --- getting-started/pull-request-lifecycle.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 0c5bd7bb79..cbf1d2b737 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -241,10 +241,10 @@ should do to help ensure that your pull request is accepted. .. _what-s-new-and-news-entries: Updating NEWS and What's New in Python --------------------------------------- +====================================== Changes that require NEWS entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, except for the following: @@ -268,7 +268,7 @@ For the last two, note the following: entry is needed. Changes that require "What's New in Python" entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------------------------- If a change is particularly interesting for end users (for example, new features, significant improvements, or backwards-incompatible changes), add an entry in @@ -284,7 +284,7 @@ in the "What's New in Python" entry. 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 `_, @@ -310,7 +310,7 @@ 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,