diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst index 3463fc1eb74..50648cd56e6 100644 --- a/doc/internals/release-process.rst +++ b/doc/internals/release-process.rst @@ -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 `_ 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 ------------------ diff --git a/utils/release-checklist b/utils/release-checklist index febbbae56c9..1d77782742f 100644 --- a/utils/release-checklist +++ b/utils/release-checklist @@ -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 ------------------------ - -* 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 ------------------------ +for 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'`` -* ``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 +* ``git tag vX.Y.0b1 -m "Sphinx X.Y.0bN"`` -for major releases ------------------- +Build Sphinx +------------ -* 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 +* open https://pypi.org/project/Sphinx/ and check for any obvious errors + +for stable and major releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * ``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