From 35e855bca84f9c61197c1a5f6dd1d1e4c947ca44 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Wed, 27 Sep 2023 20:15:39 -0500 Subject: [PATCH 1/6] docs(#1168): add directive on backporting --- developer-workflow/development-cycle.rst | 17 ++++++++++++++--- versions.rst | 3 ++- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 935f26653a..9ba4067505 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -77,10 +77,21 @@ releases; the terms are used interchangeably. These releases have a **micro version** number greater than zero. The only changes allowed to occur in a maintenance branch without debate are -bug fixes. Also, a general rule for maintenance branches is that compatibility +bug fixes. Also, a general rule for maintenance branches is that compatibility must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, -etc.). For both rules, only rare exceptions are accepted and **must** be -discussed first. +etc.). For both rules, only rare exceptions are accepted and **must** be +discussed first. Among the rare exceptions to the rules of bug fixes and compatibility, +backporting of documentation and tests is encouraged. + +Backporting serves dual purposes. First, it increases the visibility of +documentation changes since most users refer to stable versions at +`docs.python.org/3/ `_ rather +than the `docs.python.org/dev/ `_ documentation. +Second, it minimizes conflicts for future bugfix backports. + +Backporting should target enhancements in documentation and tests for +currently **stable** versions, specifically branches in a **bugfix** release cycle +or higher. A new maintenance branch is normally created when the next feature release cycle reaches feature freeze, i.e. at its first beta pre-release. diff --git a/versions.rst b/versions.rst index b712dfc6e3..e06990deb8 100644 --- a/versions.rst +++ b/versions.rst @@ -50,7 +50,8 @@ Status key but new source-only versions can be released :end-of-life: release cycle is frozen; no further changes can be pushed to it. -See also the :ref:`devcycle` page for more information about branches. +See also :ref:`devcycle` for branch information and :ref:`maintbranch` for details on +backporting documentation and test changes above the **bugfix** level. By default, the end-of-life is scheduled 5 years after the first release, but can be adjusted by the release manager of each branch. All Python 2 From 9e91c4537985ed3bc6fbd03bdcf6cc6f324555ab Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Wed, 27 Sep 2023 20:31:43 -0500 Subject: [PATCH 2/6] fix(docs): apply suggestions --- developer-workflow/development-cycle.rst | 9 ++++----- versions.rst | 3 +-- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 9ba4067505..f13bbaa060 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -77,11 +77,10 @@ releases; the terms are used interchangeably. These releases have a **micro version** number greater than zero. The only changes allowed to occur in a maintenance branch without debate are -bug fixes. Also, a general rule for maintenance branches is that compatibility -must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, -etc.). For both rules, only rare exceptions are accepted and **must** be -discussed first. Among the rare exceptions to the rules of bug fixes and compatibility, -backporting of documentation and tests is encouraged. +bug fixes and the backporting of documentation and tests. Also, a general rule +for maintenance branches is that compatibility must not be broken at any point +between sibling micro releases (3.5.1, 3.5.2, etc.). For both rules, +only rare exceptions are accepted and **must** be discussed first. Backporting serves dual purposes. First, it increases the visibility of documentation changes since most users refer to stable versions at diff --git a/versions.rst b/versions.rst index e06990deb8..6ca0d440d6 100644 --- a/versions.rst +++ b/versions.rst @@ -50,8 +50,7 @@ Status key but new source-only versions can be released :end-of-life: release cycle is frozen; no further changes can be pushed to it. -See also :ref:`devcycle` for branch information and :ref:`maintbranch` for details on -backporting documentation and test changes above the **bugfix** level. +See also the :ref:`devcycle` page for more information about branches and backporting. By default, the end-of-life is scheduled 5 years after the first release, but can be adjusted by the release manager of each branch. All Python 2 From 05cfc3f762d2dd6fde44e3f3e9be026a10cc5fa2 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Fri, 29 Sep 2023 13:48:09 -0500 Subject: [PATCH 3/6] Update developer-workflow/development-cycle.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/development-cycle.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index f13bbaa060..cb8159571f 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -77,10 +77,11 @@ releases; the terms are used interchangeably. These releases have a **micro version** number greater than zero. The only changes allowed to occur in a maintenance branch without debate are -bug fixes and the backporting of documentation and tests. Also, a general rule -for maintenance branches is that compatibility must not be broken at any point -between sibling micro releases (3.5.1, 3.5.2, etc.). For both rules, -only rare exceptions are accepted and **must** be discussed first. +bug fixes, test improvements, and edits to the documentation. +Also, a general rule for maintenance branches is that compatibility +must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, +etc.). For both rules, only rare exceptions are accepted and **must** be +discussed first. Backporting serves dual purposes. First, it increases the visibility of documentation changes since most users refer to stable versions at From 5bd59e22d8ec169f695a05ad7f4a8b486edcede4 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Thu, 5 Oct 2023 15:28:22 -0500 Subject: [PATCH 4/6] Update developer-workflow/development-cycle.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/development-cycle.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index cb8159571f..0803305843 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -83,15 +83,10 @@ must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, etc.). For both rules, only rare exceptions are accepted and **must** be discussed first. -Backporting serves dual purposes. First, it increases the visibility of -documentation changes since most users refer to stable versions at -`docs.python.org/3/ `_ rather -than the `docs.python.org/dev/ `_ documentation. -Second, it minimizes conflicts for future bugfix backports. - -Backporting should target enhancements in documentation and tests for -currently **stable** versions, specifically branches in a **bugfix** release cycle -or higher. +Back-porting changes reduces the risk of future conflicts. +For documentation, it increases the visibility of improvements, +since most readers access the `stable documentation `__ +rather than the `development documentation `__. A new maintenance branch is normally created when the next feature release cycle reaches feature freeze, i.e. at its first beta pre-release. From 7b9bff6467deb48f86de24706e957908059884a1 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Thu, 5 Oct 2023 16:08:23 -0500 Subject: [PATCH 5/6] Update developer-workflow/development-cycle.rst Co-authored-by: Hugo van Kemenade --- developer-workflow/development-cycle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 0803305843..59cf668723 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -83,7 +83,7 @@ must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, etc.). For both rules, only rare exceptions are accepted and **must** be discussed first. -Back-porting changes reduces the risk of future conflicts. +Backporting changes reduces the risk of future conflicts. For documentation, it increases the visibility of improvements, since most readers access the `stable documentation `__ rather than the `development documentation `__. From 4b7de3a94394acac68c736ed043425c122e67dad Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Thu, 5 Oct 2023 16:08:32 -0500 Subject: [PATCH 6/6] Update developer-workflow/development-cycle.rst Co-authored-by: Hugo van Kemenade --- developer-workflow/development-cycle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 59cf668723..613af736ba 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -78,7 +78,7 @@ releases; the terms are used interchangeably. These releases have a The only changes allowed to occur in a maintenance branch without debate are bug fixes, test improvements, and edits to the documentation. -Also, a general rule for maintenance branches is that compatibility +Also, a general rule for maintenance branches is that compatibility must not be broken at any point between sibling micro releases (3.5.1, 3.5.2, etc.). For both rules, only rare exceptions are accepted and **must** be discussed first.