From 55a7056242b26005e0defe36597ca0ae6eb8bab2 Mon Sep 17 00:00:00 2001 From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com> Date: Thu, 17 Sep 2026 08:38:33 +0500 Subject: [PATCH 1/5] Add NEWS entry examples page Closes python/devguide#1243. --- getting-started/news-entry-examples.rst | 26 +++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 getting-started/news-entry-examples.rst diff --git a/getting-started/news-entry-examples.rst b/getting-started/news-entry-examples.rst new file mode 100644 index 000000000..cc3d2ec06 --- /dev/null +++ b/getting-started/news-entry-examples.rst @@ -0,0 +1,26 @@ +NEWS entry examples +=================== + +This page expands the guidance in :ref:`news-entry` with concrete +examples of when a ``NEWS`` entry is (and is not) required. + +Examples that typically **do** need a ``NEWS`` entry +---------------------------------------------------- + +* a new function, method, class, or module +* a new HOWTO in the documentation +* the removal of a deprecated feature + +Examples that typically **do not** need a ``NEWS`` entry +-------------------------------------------------------- + +* a new feature was included in Python 3.13 alpha 1, but got removed in + 3.13 beta 2, before the final release of 3.13 +* a typo fix in the documentation or in a docstring +* the addition of a new test method +* the removal of a private and internal API +* code refactoring of a module with no user-visible effects + +These examples follow the existing rules under :ref:`news-entry`: +documentation-only changes, test-only changes, and strictly internal +changes with no user-visible effects generally skip a ``NEWS`` entry. From 830fdec4dc088eac7966118ff07234696477f373 Mon Sep 17 00:00:00 2001 From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com> Date: Thu, 17 Sep 2026 08:38:39 +0500 Subject: [PATCH 2/5] Link NEWS entry examples from the getting-started toctree --- getting-started/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/getting-started/index.rst b/getting-started/index.rst index c83de10a0..3d518e5d4 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -12,5 +12,6 @@ Getting started fixing-issues git-boot-camp pull-request-lifecycle + news-entry-examples getting-help ai-tools From 62a917aa7b4c3de975be5faff0ad69b3954675a0 Mon Sep 17 00:00:00 2001 From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:59:31 +0500 Subject: [PATCH 3/5] Remove news-entry-examples from Getting started toctree. --- getting-started/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/getting-started/index.rst b/getting-started/index.rst index 3d518e5d4..c83de10a0 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -12,6 +12,5 @@ Getting started fixing-issues git-boot-camp pull-request-lifecycle - news-entry-examples getting-help ai-tools From ba490c1307390f7170512235124f8271ae59b073 Mon Sep 17 00:00:00 2001 From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:04:36 +0500 Subject: [PATCH 4/5] Inline NEWS entry examples under existing guidance. --- getting-started/pull-request-lifecycle.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 5cba5f233..cc89fed58 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -233,6 +233,25 @@ For the last two, note the following: change and the original** ``NEWS`` **entry remains valid**, then no additional entry is needed. +Examples +~~~~~~~~ + +The following examples typically **do** need a ``NEWS`` entry: + +* a new function, method, class, or module +* a new HOWTO in the documentation +* the removal of a deprecated feature + +The following examples typically **do not** need a ``NEWS`` entry: + +* a new feature was included in Python 3.13 alpha 1, but got removed in + 3.13 beta 2, before the final release of 3.13 +* a typo fix in the documentation or in a docstring +* the addition of a new test method +* the removal of a private and internal API +* code refactoring of a module with no user-visible effects + + Changes that require "What's New in Python" entries --------------------------------------------------- From 267aac2647b07ffa4c023e8eb47acea22c98911e Mon Sep 17 00:00:00 2001 From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:04:46 +0500 Subject: [PATCH 5/5] Remove sibling NEWS entry examples page. --- getting-started/news-entry-examples.rst | 26 ------------------------- 1 file changed, 26 deletions(-) delete mode 100644 getting-started/news-entry-examples.rst diff --git a/getting-started/news-entry-examples.rst b/getting-started/news-entry-examples.rst deleted file mode 100644 index cc3d2ec06..000000000 --- a/getting-started/news-entry-examples.rst +++ /dev/null @@ -1,26 +0,0 @@ -NEWS entry examples -=================== - -This page expands the guidance in :ref:`news-entry` with concrete -examples of when a ``NEWS`` entry is (and is not) required. - -Examples that typically **do** need a ``NEWS`` entry ----------------------------------------------------- - -* a new function, method, class, or module -* a new HOWTO in the documentation -* the removal of a deprecated feature - -Examples that typically **do not** need a ``NEWS`` entry --------------------------------------------------------- - -* a new feature was included in Python 3.13 alpha 1, but got removed in - 3.13 beta 2, before the final release of 3.13 -* a typo fix in the documentation or in a docstring -* the addition of a new test method -* the removal of a private and internal API -* code refactoring of a module with no user-visible effects - -These examples follow the existing rules under :ref:`news-entry`: -documentation-only changes, test-only changes, and strictly internal -changes with no user-visible effects generally skip a ``NEWS`` entry.