mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Simplify development policy (#10921)
This commit is contained in:
Adam Turner
GitHub
@@ -2,35 +2,28 @@
|
||||
Sphinx's release process
|
||||
========================
|
||||
|
||||
Branch Model
|
||||
------------
|
||||
Versioning
|
||||
----------
|
||||
|
||||
Sphinx project uses following branches for developing that conforms to Semantic
|
||||
Versioning 2.0.0 (refs: https://semver.org/ ).
|
||||
Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for
|
||||
the *release segment* (e.g. 1.2.3).
|
||||
The major, minor, and micro version parts should be altered as follows:
|
||||
|
||||
``master``
|
||||
Development for MAJOR version.
|
||||
All changes including incompatible behaviors and public API updates are
|
||||
allowed.
|
||||
* The major version part should be incremented for incompatible behavior change and
|
||||
public API updates.
|
||||
|
||||
``A.x`` (ex. ``2.x``)
|
||||
Where ``A.x`` is the ``MAJOR.MINOR`` release. Used to maintain current
|
||||
MINOR release. All changes are allowed if the change preserves
|
||||
backwards-compatibility of API and features.
|
||||
* The minor version part should be incremented for most releases of Sphinx, where
|
||||
backwards-compatibility of API and features are preserves.
|
||||
|
||||
Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
|
||||
new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
|
||||
deleted and replaced by an equivalent tag.
|
||||
* The micro version part should only be incremented for urgent bugfix-only releases.
|
||||
|
||||
``A.B.x`` (ex. ``2.4.x``)
|
||||
Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release. Only
|
||||
backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
|
||||
version is used for urgent bug fix.
|
||||
When the major version part is incremented, the minor and micro version parts
|
||||
must be set to ``0``.
|
||||
When the minor version part is incremented, the micro version part must be set
|
||||
to ``0``.
|
||||
|
||||
``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
|
||||
release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
|
||||
release is needed. When new PATCH version is released, the branch will be
|
||||
deleted and replaced by an equivalent tag (ex. v2.3.1).
|
||||
New major versions should come with a beta-testing period before the final
|
||||
release.
|
||||
|
||||
|
||||
Deprecating a feature
|
||||
@@ -103,25 +96,28 @@ But you can also explicitly enable the pending ones using e.g.
|
||||
Python version support policy
|
||||
-----------------------------
|
||||
|
||||
The minimum Python version Sphinx supports is the default Python version
|
||||
installed in the oldest `Long Term Support version of
|
||||
Ubuntu <https://ubuntu.com/about/release-cycle>`_ that has standard support.
|
||||
For example, as of July 2021, Ubuntu 16.04 has just entered extended
|
||||
security maintenance (therefore, it doesn't count as standard support) and
|
||||
the oldest LTS release to consider is Ubuntu 18.04 LTS, supported until
|
||||
April 2023 and shipping Python 3.8.
|
||||
Sphinx supports at all minor versions of Python released in the past 42 months
|
||||
from the anticipated release date with a minimum of 3 minor versions of Python.
|
||||
This policy is derived from `NEP 29`_, a scientific Python domain standard.
|
||||
|
||||
.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html
|
||||
|
||||
For example, a version of Sphinx released in May 2024 would support Python 3.10,
|
||||
3.11, and 3.12.
|
||||
|
||||
This is a summary table with the current policy:
|
||||
|
||||
========== ========= ====== ======
|
||||
Date Ubuntu Python Sphinx
|
||||
========== ========= ====== ======
|
||||
April 2021 18.04 LTS 3.6+ 4, 5
|
||||
---------- --------- ------ ------
|
||||
April 2023 20.04 LTS 3.8+ 6, 7
|
||||
---------- --------- ------ ------
|
||||
April 2025 22.04 LTS 3.10+ 8
|
||||
========== ========= ====== ======
|
||||
=========== ======
|
||||
Date Python
|
||||
=========== ======
|
||||
26 Dec 2021 3.8+
|
||||
----------- ------
|
||||
14 Apr 2023 3.9+
|
||||
----------- ------
|
||||
05 Apr 2024 3.10+
|
||||
----------- ------
|
||||
04 Apr 2025 3.11+
|
||||
=========== ======
|
||||
|
||||
Release procedures
|
||||
------------------
|
||||
|
||||
@@ -1,108 +1,70 @@
|
||||
Release checklist
|
||||
=================
|
||||
|
||||
for stable releases
|
||||
-------------------
|
||||
A stable release is a release where the minor or micro version parts are
|
||||
incremented.
|
||||
A major release is a release where the major version part is incremented.
|
||||
|
||||
Checks
|
||||
------
|
||||
|
||||
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:master" and all tests has passed
|
||||
* Run ``git fetch; git status`` and check that nothing has changed
|
||||
|
||||
Bump version
|
||||
------------
|
||||
|
||||
for stable and major releases
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.Y.x" and all tests has passed
|
||||
* Run ``git fetch; git status`` and check nothing changed
|
||||
* ``python utils/bump_version.py X.Y.Z``
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump to X.Y.Z final'``
|
||||
* ``make clean``
|
||||
* ``python -m build .``
|
||||
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
|
||||
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
|
||||
* ``sh utils/bump_docker.sh X.Y.Z``
|
||||
* ``git tag vX.Y.Z -m "Sphinx X.Y.Z"``
|
||||
* ``python utils/bump_version.py --in-develop X.Y.Zb0`` (ex. 1.5.3b0)
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump version'``
|
||||
* ``git push origin X.Y.x --tags``
|
||||
* ``git checkout X.x``
|
||||
* ``git merge X.Y.x``
|
||||
* ``git push origin X.x``
|
||||
* Add new version/milestone to tracker categories
|
||||
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
|
||||
|
||||
for first beta releases
|
||||
-----------------------
|
||||
for beta releases
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:master" and all tests has passed
|
||||
* Run ``git fetch; git status`` and check nothing changed
|
||||
* ``python utils/bump_version.py X.Y.0b1``
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump to X.Y.0 beta1'``
|
||||
* ``make clean``
|
||||
* ``python -m build .``
|
||||
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
|
||||
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
|
||||
* ``git tag vX.Y.0b1 -m "Sphinx X.Y.0b1"``
|
||||
* ``python utils/bump_version.py --in-develop X.Y.0b2`` (ex. 1.6.0b2)
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump version'``
|
||||
* ``git checkout -b X.x``
|
||||
* ``git push origin X.x --tags``
|
||||
* ``git checkout master``
|
||||
* ``git merge X.x``
|
||||
* ``python utils/bump_version.py --in-develop A.B.0b0`` (ex. 1.7.0b0)
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump version'``
|
||||
* ``git push origin master``
|
||||
* open https://github.com/sphinx-doc/sphinx/settings/branches and make ``X.Y`` branch protected
|
||||
* Add new version/milestone to tracker categories
|
||||
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
|
||||
|
||||
for other beta releases
|
||||
-----------------------
|
||||
|
||||
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.x" and all tests has passed
|
||||
* Run ``git fetch; git status`` and check nothing changed
|
||||
* ``python utils/bump_version.py X.Y.0bN``
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump to X.Y.0 betaN'``
|
||||
* ``git tag vX.Y.0b1 -m "Sphinx X.Y.0bN"``
|
||||
|
||||
Build Sphinx
|
||||
------------
|
||||
|
||||
* ``make clean``
|
||||
* ``python -m build .``
|
||||
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
|
||||
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
|
||||
* ``git tag vX.Y.0bN -m "Sphinx X.Y.0bN"``
|
||||
* ``python utils/bump_version.py --in-develop X.Y.0bM`` (ex. 1.6.0b3)
|
||||
* Check diff by `git diff``
|
||||
* ``git commit -am 'Bump version'``
|
||||
* ``git push origin X.x --tags``
|
||||
* ``git checkout master``
|
||||
* ``git merge X.x``
|
||||
* ``git push origin master``
|
||||
* Add new version/milestone to tracker categories
|
||||
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
|
||||
* open https://pypi.org/project/Sphinx/ and check for any obvious errors
|
||||
|
||||
for major releases
|
||||
------------------
|
||||
for stable and major releases
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* open "https://github.com/sphinx-doc/sphinx/actions?query=branch:X.x" and all tests has passed
|
||||
* Run ``git fetch; git status`` and check nothing changed
|
||||
* Run ``git add sphinx``
|
||||
* Run ``git commit -am 'Update message catalogs'``
|
||||
* ``python utils/bump_version.py X.Y.0``
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump to X.Y.0 final'``
|
||||
* ``make clean``
|
||||
* ``python -m build .``
|
||||
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
|
||||
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors
|
||||
* ``sh utils/bump_docker.sh X.Y.Z``
|
||||
* ``git tag vX.Y.0 -m "Sphinx X.Y.0"``
|
||||
* ``python utils/bump_version.py --in-develop X.Y.1b0`` (ex. 1.6.1b0)
|
||||
|
||||
Bump to next development version
|
||||
--------------------------------
|
||||
|
||||
for stable and major releases
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``python utils/bump_version.py --in-develop X.Y.Z+1b0`` (ex. 1.5.3b0)
|
||||
|
||||
for beta releases
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``python utils/bump_version.py --in-develop X.Y.0bN+1`` (ex. 1.6.0b2)
|
||||
|
||||
Commit version bump
|
||||
-------------------
|
||||
|
||||
* Check diff by ``git diff``
|
||||
* ``git commit -am 'Bump version'``
|
||||
* ``git push origin X.x --tags``
|
||||
* ``git checkout master``
|
||||
* ``git merge X.x``
|
||||
* ``git push origin master``
|
||||
* open https://github.com/sphinx-doc/sphinx/settings/branches and make ``A.B`` branch *not* protected
|
||||
* ``git checkout A.B`` (checkout old stable)
|
||||
* Run ``git tag A.B -m "Sphinx A.B"`` to paste a tag instead branch
|
||||
* Run ``git push origin :A.B --tags`` to remove old stable branch
|
||||
* open https://readthedocs.org/dashboard/sphinx/versions/ and enable the released version
|
||||
* ``git push origin master --tags``
|
||||
|
||||
Final steps
|
||||
-----------
|
||||
|
||||
* Add new version/milestone to tracker categories
|
||||
* Write announcement and send to sphinx-dev, sphinx-users and python-announce
|
||||
|
||||
Reference in New Issue
Block a user