Sphinx’s release process¶
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
When the minor version part is incremented, the micro version part must be set
New major versions should come with a beta-testing period before the final release.
Deprecating a feature¶
There are a couple reasons that code in Sphinx might be deprecated:
If a feature has been improved or modified in a backwards-incompatible way, the old feature or behavior will be deprecated.
Sometimes Sphinx will include a backport of a Python library that’s not included in a version of Python that Sphinx currently supports. When Sphinx no longer needs to support the older version of Python that doesn’t include the library, the library will be deprecated in Sphinx.
As the Deprecation policy describes, the first release of Sphinx that
deprecates a feature (
A.B) should raise a
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
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
RemovedInSphinx40Warningwill be a subclass of
DeprecationWarningthen, and gets displayed by default.
Sphinx 4.0 will remove the feature outright.
Sphinx will enable its
RemovedInNextVersionWarning warnings by default, if
PYTHONWARNINGS is not set. Therefore you can disable them
PYTHONWARNINGS= make html(Linux/Mac)
export PYTHONWARNINGS=and do
set PYTHONWARNINGS=and do
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 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.
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:
26 Dec 2021
14 Apr 2023
05 Apr 2024
04 Apr 2025
The release procedures are listed in