Sphinx’s release process
Sphinx’s release process
Sphinx project uses following branches for developing that conforms to Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
Development for MAJOR version. All changes including incompatible behaviors and public API updates are allowed.
MAJOR.MINORrelease. Used to maintain current MINOR release. All changes are allowed if the change preserves backwards-compatibility of API and features.
Only the most recent
MAJOR.MINORbranch is currently retained. When a new MAJOR version is released, the old
MAJOR.MINORbranch will be deleted and replaced by an equivalent tag.
MAJOR.MINOR.PATCHrelease. Only backwards-compatible bug fixes are allowed. In Sphinx project, PATCH version is used for urgent bug fix.
MAJOR.MINOR.PATCHbranch will be branched from the
vprefixed 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).
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 enabled:
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 DeprecationWarning then, 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 using:
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.
The release procedures are listed in