Skip to content

Commit

Permalink
docs(#1168): add directive on backporting
Browse files Browse the repository at this point in the history
  • Loading branch information
JacobCoffee committed Sep 28, 2023
1 parent 4baaf76 commit 35e855b
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 4 deletions.
17 changes: 14 additions & 3 deletions developer-workflow/development-cycle.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/ <https://docs.python.org/3/>`_ rather
than the `docs.python.org/dev/ <https://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.
Expand Down
3 changes: 2 additions & 1 deletion versions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 35e855b

Please sign in to comment.