Skip to content

Commit 0200a75

Browse files
AA-TurnerAA-Turner
authored
Simplify development policy (#10921)
1 parent 592b46c commit 0200a75

File tree

2 files changed

+82
-124
lines changed

2 files changed

+82
-124
lines changed

‎doc/internals/release-process.rst

+35-39
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,28 @@
22
Sphinx's release process
33
========================
44

5-
Branch Model
6-
------------
5+
Versioning
6+
----------
77

8-
Sphinx project uses following branches for developing that conforms to Semantic
9-
Versioning 2.0.0 (refs: https://semver.org/ ).
8+
Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for
9+
the *release segment* (e.g. 1.2.3).
10+
The major, minor, and micro version parts should be altered as follows:
1011

11-
``master``
12-
Development for MAJOR version.
13-
All changes including incompatible behaviors and public API updates are
14-
allowed.
12+
* The major version part should be incremented for incompatible behavior change and
13+
public API updates.
1514

16-
``A.x`` (ex. ``2.x``)
17-
Where ``A.x`` is the ``MAJOR.MINOR`` release. Used to maintain current
18-
MINOR release. All changes are allowed if the change preserves
19-
backwards-compatibility of API and features.
15+
* The minor version part should be incremented for most releases of Sphinx, where
16+
backwards-compatibility of API and features are preserves.
2017

21-
Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
22-
new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
23-
deleted and replaced by an equivalent tag.
18+
* The micro version part should only be incremented for urgent bugfix-only releases.
2419

25-
``A.B.x`` (ex. ``2.4.x``)
26-
Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release. Only
27-
backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
28-
version is used for urgent bug fix.
20+
When the major version part is incremented, the minor and micro version parts
21+
must be set to ``0``.
22+
When the minor version part is incremented, the micro version part must be set
23+
to ``0``.
2924

30-
``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
31-
release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
32-
release is needed. When new PATCH version is released, the branch will be
33-
deleted and replaced by an equivalent tag (ex. v2.3.1).
25+
New major versions should come with a beta-testing period before the final
26+
release.
3427

3528

3629
Deprecating a feature
@@ -103,25 +96,28 @@ But you can also explicitly enable the pending ones using e.g.
10396
Python version support policy
10497
-----------------------------
10598

106-
The minimum Python version Sphinx supports is the default Python version
107-
installed in the oldest `Long Term Support version of
108-
Ubuntu <https://ubuntu.com/about/release-cycle>`_ that has standard support.
109-
For example, as of July 2021, Ubuntu 16.04 has just entered extended
110-
security maintenance (therefore, it doesn't count as standard support) and
111-
the oldest LTS release to consider is Ubuntu 18.04 LTS, supported until
112-
April 2023 and shipping Python 3.8.
99+
Sphinx supports at all minor versions of Python released in the past 42 months
100+
from the anticipated release date with a minimum of 3 minor versions of Python.
101+
This policy is derived from `NEP 29`_, a scientific Python domain standard.
102+
103+
.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html
104+
105+
For example, a version of Sphinx released in May 2024 would support Python 3.10,
106+
3.11, and 3.12.
113107

114108
This is a summary table with the current policy:
115109

116-
========== ========= ====== ======
117-
Date Ubuntu Python Sphinx
118-
========== ========= ====== ======
119-
April 2021 18.04 LTS 3.6+ 4, 5
120-
---------- --------- ------ ------
121-
April 2023 20.04 LTS 3.8+ 6, 7
122-
---------- --------- ------ ------
123-
April 2025 22.04 LTS 3.10+ 8
124-
========== ========= ====== ======
110+
=========== ======
111+
Date Python
112+
=========== ======
113+
26 Dec 2021 3.8+
114+
----------- ------
115+
14 Apr 2023 3.9+
116+
----------- ------
117+
05 Apr 2024 3.10+
118+
----------- ------
119+
04 Apr 2025 3.11+
120+
=========== ======
125121

126122
Release procedures
127123
------------------

‎utils/release-checklist

+47-85
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,70 @@
11
Release checklist
22
=================
33

4-
for stable releases
5-
-------------------
4+
A stable release is a release where the minor or micro version parts are
5+
incremented.
6+
A major release is a release where the major version part is incremented.
7+
8+
Checks
9+
------
10+
11+
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:master" and all tests has passed
12+
* Run ``git fetch; git status`` and check that nothing has changed
13+
14+
Bump version
15+
------------
16+
17+
for stable and major releases
18+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
619

7-
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.Y.x" and all tests has passed
8-
* Run ``git fetch; git status`` and check nothing changed
920
* ``python utils/bump_version.py X.Y.Z``
1021
* Check diff by ``git diff``
1122
* ``git commit -am 'Bump to X.Y.Z final'``
12-
* ``make clean``
13-
* ``python -m build .``
14-
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
15-
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
16-
* ``sh utils/bump_docker.sh X.Y.Z``
1723
* ``git tag vX.Y.Z -m "Sphinx X.Y.Z"``
18-
* ``python utils/bump_version.py --in-develop X.Y.Zb0`` (ex. 1.5.3b0)
19-
* Check diff by ``git diff``
20-
* ``git commit -am 'Bump version'``
21-
* ``git push origin X.Y.x --tags``
22-
* ``git checkout X.x``
23-
* ``git merge X.Y.x``
24-
* ``git push origin X.x``
25-
* Add new version/milestone to tracker categories
26-
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
27-
28-
for first beta releases
29-
-----------------------
30-
31-
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:master" and all tests has passed
32-
* Run ``git fetch; git status`` and check nothing changed
33-
* ``python utils/bump_version.py X.Y.0b1``
34-
* Check diff by ``git diff``
35-
* ``git commit -am 'Bump to X.Y.0 beta1'``
36-
* ``make clean``
37-
* ``python -m build .``
38-
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
39-
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
40-
* ``git tag vX.Y.0b1 -m "Sphinx X.Y.0b1"``
41-
* ``python utils/bump_version.py --in-develop X.Y.0b2`` (ex. 1.6.0b2)
42-
* Check diff by ``git diff``
43-
* ``git commit -am 'Bump version'``
44-
* ``git checkout -b X.x``
45-
* ``git push origin X.x --tags``
46-
* ``git checkout master``
47-
* ``git merge X.x``
48-
* ``python utils/bump_version.py --in-develop A.B.0b0`` (ex. 1.7.0b0)
49-
* Check diff by ``git diff``
50-
* ``git commit -am 'Bump version'``
51-
* ``git push origin master``
52-
* open https://github.com/sphinx-doc/sphinx/settings/branches and make ``X.Y`` branch protected
53-
* Add new version/milestone to tracker categories
54-
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
5524

56-
for other beta releases
57-
-----------------------
25+
for beta releases
26+
~~~~~~~~~~~~~~~~~
5827

59-
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.x" and all tests has passed
60-
* Run ``git fetch; git status`` and check nothing changed
6128
* ``python utils/bump_version.py X.Y.0bN``
6229
* Check diff by ``git diff``
6330
* ``git commit -am 'Bump to X.Y.0 betaN'``
64-
* ``make clean``
65-
* ``python -m build .``
66-
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
67-
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
68-
* ``git tag vX.Y.0bN -m "Sphinx X.Y.0bN"``
69-
* ``python utils/bump_version.py --in-develop X.Y.0bM`` (ex. 1.6.0b3)
70-
* Check diff by `git diff``
71-
* ``git commit -am 'Bump version'``
72-
* ``git push origin X.x --tags``
73-
* ``git checkout master``
74-
* ``git merge X.x``
75-
* ``git push origin master``
76-
* Add new version/milestone to tracker categories
77-
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
31+
* ``git tag vX.Y.0b1 -m "Sphinx X.Y.0bN"``
7832

79-
for major releases
80-
------------------
33+
Build Sphinx
34+
------------
8135

82-
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.x" and all tests has passed
83-
* Run ``git fetch; git status`` and check nothing changed
84-
* Run ``git add sphinx``
85-
* Run ``git commit -am 'Update message catalogs'``
86-
* ``python utils/bump_version.py X.Y.0``
87-
* Check diff by ``git diff``
88-
* ``git commit -am 'Bump to X.Y.0 final'``
8936
* ``make clean``
9037
* ``python -m build .``
9138
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
92-
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
39+
* open https://pypi.org/project/Sphinx/ and check for any obvious errors
40+
41+
for stable and major releases
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
9344
* ``sh utils/bump_docker.sh X.Y.Z``
94-
* ``git tag vX.Y.0 -m "Sphinx X.Y.0"``
95-
* ``python utils/bump_version.py --in-develop X.Y.1b0`` (ex. 1.6.1b0)
45+
46+
Bump to next development version
47+
--------------------------------
48+
49+
for stable and major releases
50+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+
* ``python utils/bump_version.py --in-develop X.Y.Z+1b0`` (ex. 1.5.3b0)
53+
54+
for beta releases
55+
~~~~~~~~~~~~~~~~~
56+
57+
* ``python utils/bump_version.py --in-develop X.Y.0bN+1`` (ex. 1.6.0b2)
58+
59+
Commit version bump
60+
-------------------
61+
9662
* Check diff by ``git diff``
9763
* ``git commit -am 'Bump version'``
98-
* ``git push origin X.x --tags``
99-
* ``git checkout master``
100-
* ``git merge X.x``
101-
* ``git push origin master``
102-
* open https://github.com/sphinx-doc/sphinx/settings/branches and make ``A.B`` branch *not* protected
103-
* ``git checkout A.B`` (checkout old stable)
104-
* Run ``git tag A.B -m "Sphinx A.B"`` to paste a tag instead branch
105-
* Run ``git push origin :A.B --tags`` to remove old stable branch
106-
* open https://readthedocs.org/dashboard/sphinx/versions/ and enable the released version
64+
* ``git push origin master --tags``
65+
66+
Final steps
67+
-----------
68+
10769
* Add new version/milestone to tracker categories
10870
* Write announcement and send to sphinx-dev, sphinx-users and python-announce

0 commit comments

Comments
 (0)