Sphinx 的发布流程¶

版本控制¶

Sphinx 遵循 PEP 440 版本，采用 major.minor.micro 方案用于发布段（例如 1.2.3）。主版本、次版本和微版本部分应按如下方式更改：

主版本部分应在不兼容行为更改和公共 API 更新时递增。
次版本部分应在大多数 Sphinx 发布时递增，此时 API 和功能的向后兼容性得到保留。
微版本部分应仅在紧急的仅修复错误的发布时递增。

当主版本部分递增时，次版本和微版本部分必须设置为 0。当次版本部分递增时，微版本部分必须设置为 0。

新的主版本在最终发布前应有一个 Beta 测试期。

废弃功能¶

Sphinx 中的代码可能被废弃有几个原因：

如果一个功能以不兼容的方式进行了改进或修改，旧的功能或行为将被废弃。
有时 Sphinx 会包含一个 Python 库的向后移植版本，该库不包含在 Sphinx 当前支持的 Python 版本中。当 Sphinx 不再需要支持不包含该库的旧版本 Python 时，该库将在 Sphinx 中被废弃。

正如废弃策略所述，Sphinx 废弃某功能 (A.B) 的第一个版本应在调用废弃功能时引发 RemovedInSphinxXXWarning（其中 XX 是该功能将被移除的 Sphinx 版本）。假设我们有良好的测试覆盖率，这些警告在启用警告运行测试套件时会转换为错误。

pytest -Wall

因此，在添加 RemovedInSphinxXXWarning 时，您需要消除或抑制运行测试时生成的任何警告。

废弃策略¶

MAJOR 和 MINOR 版本可能会废弃以前版本中的某些功能。如果一个功能在 A.x 版本中被废弃，它将在所有 A.x.x 版本中继续工作（对于所有 x 版本）。它将在所有 B.x.x 版本中继续工作，但会引发废弃警告。废弃功能将在 C.0.0 版本中移除。这意味着废弃功能将至少在 2 个 MAJOR 版本中继续工作。

因此，例如，如果我们决定在 Sphinx 2.x 中开始废弃一个函数：

Sphinx 2.x 将包含该函数的向后兼容副本，并引发 RemovedInSphinx40Warning。这是 PendingDeprecationWarning 的子类，即它默认不会显示。
Sphinx 3.x 仍将包含向后兼容副本，但 RemovedInSphinx40Warning 将是 DeprecationWarning 的子类，并默认显示。
Sphinx 4.0 将彻底移除该功能。

废弃警告¶

如果未设置 PYTHONWARNINGS，Sphinx 将默认启用其 RemovedInNextVersionWarning 警告。因此，您可以使用以下方式禁用它们：

PYTHONWARNINGS= make html (Linux/Mac)
export PYTHONWARNINGS= 然后执行 make html (Linux/Mac)
set PYTHONWARNINGS= 然后执行 make html (Windows)

但您也可以使用例如 PYTHONWARNINGS=default 显式启用待处理的警告（有关更多详细信息，请参阅 Python 文档中关于配置警告的部分）。

Python 版本支持策略¶

Sphinx 支持在预期发布日期前三年内发布的所有 Python 次要版本，至少包含 3 个 Python 次要版本。此策略源自科学 Python 领域标准 SPEC 0。

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

这是当前策略的摘要表：

日期	Python
2023 年 10 月 5 日	3.10+
2024 年 10 月 4 日	3.11+
2025 年 10 月 24 日	3.12+
2026 年 10 月 1 日	3.13+
2027 年 10 月 1 日	3.14+

发布程序¶

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