sphinx的释放过程¶
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.
弃用功能¶
Sphinx中的代码可能会被弃用，这有两个原因：
如果某个功能以向后不兼容的方式进行了改进或修改，则旧功能或行为将被弃用。
有时候，Sphinx将包含Python库的一个后端口，而Sphinx当前支持的Python版本中没有包含该库。当Sphinx不再需要支持不包含库的Python旧版本时，Sphinx中将不推荐使用该库。
正如：ref:deprecision policy`所描述的，在调用不推荐使用的功能时，第一个不推荐使用的功能的Sphinx版本（`a.B`）应该发出一个“RemovedInSphinxXXWarning``（其中``XX``是将删除该功能的Sphinx版本）。假设我们有良好的测试覆盖率，在运行启用警告的测试套件时，这些警告将转换为错误：
pytest -Wall
因此，在添加“RemovedInSphinxXXWarning”时，需要消除或消除运行测试时生成的任何警告。
弃用政策¶
主要版本和次要版本可能会贬低以前版本中的某些功能。如果某个特性在版本a.x中被弃用，它将继续在所有a.x.x版本中工作（对于x的所有版本）。它将继续在所有B.x.x版本中工作，但会引发不推荐使用的警告。不推荐使用的功能将在C.0.0中删除。这意味着不推荐的特性将在至少两个主要版本中工作。
因此，例如，如果我们决定开始对Sphinx 2.x中的函数进行弃用：
sphinx2.x将包含该函数的向后兼容副本，该副本将引发“RemovedInSphinx40Warning”。这是：exc:python:pendingdprecationwarning，即默认不显示。
Sphinx3.x仍将包含向后兼容的副本，但“RemovedInSphinx40Warning”将是exc:`python:弃用警告`然后，默认显示。
斯芬克斯4.0将彻底删除该功能。
弃用警告¶
Sphinx将在默认情况下启用其“RemovedInNextVersionWarning”警告，前提是：envvar：`python:PYTHONWARNINGS`未设置。因此，您可以使用以下方法禁用它们：
运行
PYTHONWARNINGS= make html（适用于Linux/Mac系统），注意中间的空格先运行
export PYTHONWARNINGS=然后make html（适用于Linux/Mac系统）先运行
set PYTHONWARNINGS=然后make html（适用于 Windows 系统）
但您也可以使用“PYTHONWARNINGS=default`”显式地启用挂起的警告（请参阅：ref:Python docs on configuring warnings）以获取更多详细信息。
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:
Date |
Python |
|---|---|
26 Dec 2021 |
3.8+ |
14 Apr 2023 |
3.9+ |
05 Apr 2024 |
3.10+ |
04 Apr 2025 |
3.11+ |
24 Apr 2026 |
3.12+ |
释放程序¶
The release procedures are listed in utils/release-checklist.rst.