Sphinx のリリースプロセス¶
バージョニング¶
Sphinx は、PEP 440 のバージョンに従い、リリースセグメント (例: 1.2.3) に major.minor.micro スキームを使用します。メジャー、マイナー、およびマイクロバージョンの部分は、次のように変更する必要があります。
メジャーバージョン部分は、互換性のない動作の変更およびパブリック API の更新のためにインクリメントする必要があります。
マイナーバージョン部分は、API および機能の後方互換性が維持される、Sphinx のほとんどのリリースでインクリメントする必要があります。
マイクロバージョン部分は、緊急のバグ修正のみのリリースでのみインクリメントする必要があります。
メジャーバージョン部分がインクリメントされると、マイナーおよびマイクロバージョン部分は 0 に設定する必要があります。マイナーバージョン部分がインクリメントされると、マイクロバージョン部分は 0 に設定する必要があります。
新しいメジャーバージョンは、最終リリース前にベータテスト期間が必要です。
機能の非推奨化¶
Sphinx のコードが非推奨になる理由はいくつかあります。
機能が後方互換性のない方法で改善または変更された場合、古い機能または動作は非推奨になります。
場合によっては、Sphinx は、現在 Sphinx がサポートしている Python のバージョンに含まれていない 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 は、予想されるリリース日から過去 3 年間にリリースされたすべてのマイナーバージョンの 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 に記載されています。