スフィンクスの再生過程

分岐機構モデル

Sphinxプロジェクトは、以下の分岐を使用して、意味バージョン2.0.0(https://semver.org/)に適合する製品を開発します。

master

主なバージョンの開発。互換性のないアクションおよび共通API更新を含むすべての変更を可能にします。

A.x (前) 2.x

どこへ行くのか. A.x はい。 MAJOR.MINOR 釈放する。現在のサブバージョンを維持するために使用される。APIと機能の後方互換性が保持されている変更があれば、すべての変更が許可されます。

最新のしかありません MAJOR.MINOR 支店は現在も維持されている。新しい主要バージョンが発表されると古いのは MAJOR.MINOR ノードは削除され,等価なフラグに置き換えられる.

A.B.x (前) 2.4.x

どこへ行くのか. A.B.x はい。 MAJOR.MINOR.PATCH 釈放する。後方互換性のエラー修復のみを許可する。Sphinxプロジェクトでは、パッチバージョンはエラーを緊急修復するために使用されます。

MAJOR.MINOR.PATCH 分枝は v プレフィックス付きバージョンラベル(例えば緊急配布が必要な場合は,v 2.3.0からの2.3.1)を生成する.新しいパッチバージョンが発行されると、ブランチは削除され、等価なフラグ(例えば、)によって削除される。V 2.3.1).

ある機能のご利用はお勧めしておりません

Sphinxのコードが破棄される可能性があります理由はいくつかあります

  • ある機能が後方互換性のない方法で改善または修正された場合、古い機能または動作は破棄されるであろう。

  • SphinxにはPythonライブラリのバックポートが含まれることがありますが、Sphinxが現在サポートしているPythonバージョンにはライブラリが含まれていません。Sphinxがライブラリの古いバージョンを含まないPythonをサポートする必要がなくなった場合、Sphinxはライブラリをサポートしなくなります。

として 策略を捨てる. これはSphinxの最初のバージョンで機能を捨てたと説明しています (A.B )誘発すべき RemovedInSphinxXXWarning (凡人) XX 使用を推奨しない機能を呼び出す際には,その機能のSphinxバージョンを削除する).私たちが良いテストカバー率を持っていると仮定して、警告を有効にしてテストキットを実行すると、これらの警告はエラーに変換されます。

pytest -Wall

そこで追加されています RemovedInSphinxXXWarning テスト時に生成された任意の警告を除去または静かに実行する必要があります。

策略を捨てる.

第1のバージョンおよび第2のバージョンは、以前のバージョンのいくつかの機能を破棄する可能性がある。ある機能がA.xバージョンで破棄された場合、それは、すべてのA.x.xバージョンで動作し続ける(すべてのバージョンのxに適用される)。それはすべてのB.x.xバージョンで働き続けるだろうが、廃棄警告を出すだろう。使用を推奨しない機能はC.0.0で削除する.これは、少なくとも2つの主要バージョンにおいて、使用を推奨しない機能が機能することを意味する。

したがって、例えば、Sphinx 2.xにおいてある関数を破棄し始めることにした場合:

  • Sphinx 2.xは、関数の後方互換性コピーを含み、このコピーが開始される RemovedInSphinx40Warning それがそうです。これは子類です PendingDeprecationWarning すなわち,デフォルトでは表示されない.

  • Sphinx 3.xは依然として後方互換性のコピーを含むが、 RemovedInSphinx40Warning そうなる子類 DeprecationWarning そして、デフォルトの場合には和を表示します。

  • Sphinx 4.0は、この機能を完全に削除します。

警告のご利用はおすすめしておりません

ライオンの顔像は RemovedInNextVersionWarning デフォルトの場合,以下のような場合があれば警告とする. PYTHONWARNINGS 設定されていません。したがって、以下のコマンドを使用してそれらを無効にすることができます。

  • PYTHONWARNINGS= make html (Linux/Mac)

  • export PYTHONWARNINGS= そしてやります make html (Linux/Mac)

  • set PYTHONWARNINGS= そしてやります make html (窓口)

しかし、あなたはまた、例えば、保留されたファイルを明示的に有効にすることもできます。 PYTHONWARNINGS=default (会いましょう) Python docs on configuring warnings )より詳細な情報を知ることができます。

放行プログラム.

リリースプログラムは中に記載されています utils/release-checklist それがそうです。