Sphinx的版本发布过程¶

版本编号¶

Sphinx遵循 PEP 440 版本，采用 major.minor.micro 方案作为 版本号分段 （例如1.2.3）。major, minor和micro部分应按以下方式变更：

主版本号major应在不兼容的行为更改和公共API更新时递增。
次版本号minor应在大多数Sphinx版本中递增，次版本号间保留API和功能的向后兼容性。
微版本号micro仅应在紧急的、仅修复bug的版本中递增。

当主版本号major递增时，次版本号minor和微版本号micro必须设置为 0。当次版本号minor递增时，微版本号micro必须设置为 0。

新主版本应在最终发布之前经历beta测试期。

弃用一个特性¶

Sphinx中的代码可能会因为两个原因被弃用：

如果某个功能以向后不兼容的方式进行了改进或修改，则旧功能或行为将被弃用。
有时候，Sphinx将包含Python库的一个后端口，而Sphinx当前支持的Python版本中没有包含该库。当Sphinx不再需要支持不包含库的Python旧版本时，Sphinx中将不推荐使用该库。

正如弃用策略所描述的，在调用不推荐使用的功能时，第一个不推荐使用的功能的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。这是 PendingDeprecationWarning，即默认不显示。
Sphinx3.x仍将包含向后兼容的副本，但 RemovedInSphinx40Warning 将是 DeprecationWarning 的子类，并且默认显示。
Sphinx 4.0将彻底删除该功能。

弃用警告¶

Sphinx将在默认情况下启用其“RemovedInNextVersionWarning”警告，前提是 PYTHONWARNINGS 未设置。因此，您可以使用以下方法禁用它们：

运行 PYTHONWARNINGS= make html （适用于Linux/Mac系统），注意中间的空格
先运行 export PYTHONWARNINGS= 然后 make html （适用于Linux/Mac系统）
先运行 set PYTHONWARNINGS= 然后 make html （适用于 Windows 系统）

但您也可以使用 PYTHONWARNINGS=default 显式地启用挂起的警告（请参阅 Python docs on configuring warnings）以获取更多详细信息。

对Python版本的支持策略¶

Sphinx支持从预期发布日期起过去3年内发布的所有Python次版本，即至少支持3个Python次版本。该政策源自科学Python领域标准 SPEC 0。

例如，2025年5月发布的Sphinx版本将支持Python 3.11、3.12和3.13。

这是当前政策的摘要表：

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+

发布流程¶

发布流程列在 utils/release-checklist.rst 中。