Sphinx's release process

Versioning

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:

  • The major version part should be incremented for incompatible behavior change and public API updates.

  • The minor version part should be incremented for most releases of Sphinx, where backwards-compatibility of API and features are preserves.

  • The micro version part should only be incremented for urgent bugfix-only releases.

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.

New major versions should come with a beta-testing period before the final release.

非推奨の機能

次の2つの理由からSphinx内のコードは非推奨なものとなるかもしれません:

  • ある機能が後方互換のない方法で改良、修正された場合、古い機能，動作は非推奨となります。

  • Sphinxが現在サポートしているPythonのバージョンで収録されていないPythonライブラリを，Sphinxはバックポートとして収録することがあります。Pythonの旧バージョンで，当該ライブラリを収録していないものについてサポートをSphinxが打ち切るときに、そのライブラリはSphinxで非推奨となります。

As the 非推奨についての方針 describes, the first release of Sphinx that deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning (where XX is the Sphinx version where the feature will be removed) when the deprecated feature is invoked. Assuming we have good test coverage, these warnings are converted to errors when running the test suite with warnings enabled:

pytest -Wall

Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or silence any warnings generated when running the tests.

非推奨についての方針

MAJOR and MINOR releases may deprecate certain features from previous releases. If a feature is deprecated in a release A.x, it will continue to work in all A.x.x versions (for all versions of x). It will continue to work in all B.x.x versions but raise deprecation warnings. Deprecated features will be removed at the C.0.0. It means the deprecated feature will work during 2 MAJOR releases at least.

So, for example, if we decided to start the deprecation of a function in Sphinx 2.x:

  • Sphinx 2.x will contain a backwards-compatible replica of the function which will raise a RemovedInSphinx40Warning. This is a subclass of PendingDeprecationWarning, i.e. it will not get displayed by default.

  • Sphinx 3.x will still contain the backwards-compatible replica, but RemovedInSphinx40Warning will be a subclass of DeprecationWarning then, and gets displayed by default.

  • Sphinx 4.0 will remove the feature outright.

Deprecation warnings

Sphinx will enable its RemovedInNextVersionWarning warnings by default, if PYTHONWARNINGS is not set. Therefore you can disable them using:

  • PYTHONWARNINGS= make html (Linux/Mac)

  • export PYTHONWARNINGS= として、 make html を実行する(Linux/Mac)

  • set PYTHONWARNINGS= として make html を実行する(Windows)

But you can also explicitly enable the pending ones using e.g. PYTHONWARNINGS=default (see the Python docs on configuring warnings) for more details.

Python version support policy

Sphinx supports at all minor versions of Python released in the past 3 years from the anticipated release date with a minimum of 3 minor versions of Python. This policy is derived from SPEC 0, a scientific Python domain standard.

For example, a version of Sphinx released in May 2025 would support Python 3.11, 3.12, and 3.13.

This is a summary table with the current policy:

Date

Python

05 Oct 2023

3.10+

04 Oct 2024

3.11+

24 Oct 2025

3.12+

01 Oct 2026

3.13+

01 Oct 2027

3.14+

Release procedures

The release procedures are listed in utils/release-checklist.rst.