非推奨に関する方針#

多くのユーザーやその他のパッケージは、Qiskit のさまざまな部分に依存しています。 コードに変更を加えるときはいつでも、ユーザーがすでに作成したコードを壊すことなく調整するための十分な時間をユーザーに与えるようにする必要があります。

最も重要なことは、どうしても必要な場合を除いて、公開されているインターフェースを 変更しない ことです。 物事を追加することは問題ありません。物事を取り除くことはユーザーにとって迷惑ですが、十分な注意を払って合理的に処理できます。動作を変更すると一般的に、ユーザーはQiskitの後続の2つのバージョンで動作するコードを記述できなくなり、これは受け入れられません。

ユーザーは、Qiskit 開発者が内部または広く使用されていないと見なす関数、クラス、およびメソッドを使用することが多いことに注意してください。 「これは埋もれているので、誰も使用しないだろう」と思い込まないでください。 公開されている場合は、ポリシーに従います。 ここでの唯一の例外は、明示的に内部的な関数とモジュールです。つまり、名前の先頭がアンダースコア (_) で始まるものです。

指針は次のとおりです。

  • 少なくとも3か月または2つの完全なバージョンサイクルの間、有効な警告なしにコードを削除または変更してはなりません。

  • 警告を出さない有効な目標を達成する方法が常になければなりません。

  • 明示的に内部に存在しない関数が使用されていないと思い込まないでください。

  • すべての非推奨、変更、および削除は API の変更と見なされ、 安定版ブランチポリシー に従って、パッチ リリースではなくマイナー リリースでのみ発生する可能性があります。

機能の削除#

機能 (クラス、関数、関数パラメーターなど) を削除する場合は、次の手順に従います。

  1. 警告が発行される前に、1 つのマイナー バージョンに対して代替パスを設定する必要があります。 たとえば、関数 foo() を bar() に置き換えたい場合、 foo() 内で警告を発行する前に、両方の関数を少なくとも 1 回リリースする必要があります。 古いパスからすぐに PendingDeprecationWarning を発行できます。

    理由 : アップグレードしたらすぐに、コードを壊さずにスワップする時間を与える必要があります。

  2. 少なくとも 1 つのマイナー バージョンの代替パスが設定されたら、 非推奨の警告を発行 します。 非推奨のすべてのパス、代替パス、および非推奨の理由を記載した deprecations セクションを含むリリース ノートを追加します。 テストを更新して、警告をテスト します。

    理由 : ユーザーが実際に行ったときの驚きを最小限に抑えるために、削除は少なくとも 1 つのバージョンで目立つようにする必要があります。

  3. 古い機能の削除日を設定し、到達したらそれ (および警告) を削除します。 これは、警告のあるバージョンが最初にリリースされてから 3 か月以上経過している必要があり、警告の直後のマイナー バージョンであってはなりません。 すべての削除を一覧表示する upgrade リリースノートを追加します。 たとえば、代替パスが 0.19.0 で提供され、警告が 0.20.0 で追加された場合、 0.20.0 から 3 か月以上後に 0.21.0 がリリースされたとしても、削除される最も古いバージョンは 0.22.0 です。

    注釈

    これらは最小要件です。 重要な機能またはコア機能を削除する場合は、少なくとも追加のマイナー バージョンをユーザーに提供してください。

    理由 : ユーザーがこれらのメッセージを見て、調整する時間が必要です。 すべてのユーザーが Qiskit のバージョンをすぐに更新するわけではなく、一部のユーザーはマイナー バージョンをスキップする場合があります。

機能が非推奨としてマークされている場合、その機能は削除される予定ですが、ユーザーは引き続き正しく機能するために信頼できるはずです。 「非推奨」とマークされた機能は凍結されていると見なされます。 削除されるまで重要なバグ修正を維持することを約束しますが、新しい機能をマージすることはありません。

動作の変更#

2 つのバージョンで両方のオプションを利用可能にし、警告を発行できるようにする必要があるため、削除せずに動作を変更することは特に管理が困難です。 たとえば、関数からの戻り値の型を変更すると、ほとんどの場合、API が中断されます。これは、ユーザーにとってイライラし、Qiskit の使用を困難にします。

ここでの最善の解決策は、多くの場合、新しい関数を作成してから、上記の 削除手順 を使用することです。

既存のコードの動作を絶対に変更する必要がある場合 (バグの修正以外) は、このドキュメントの上部にある指針を適用するために最善の判断を下す必要があります。 通常、動作の変化に対する最も適切な警告は FutureWarning です。 変更を行う方法のいくつかの可能性:

  • 関数のデフォルトの動作を変更する場合は、キーワード引数を追加して、古い動作と新しい動作を選択することを検討してください。 時が来たら、キーワード引数が指定されていない場合 (たとえば、 None の場合)、新しい値がすぐにデフォルトになることを示す FutureWarning を発行できます。 動作を変更した後、このキーワード引数を削除するには、通常の非推奨期間を経過する必要があります。 これには、両方のサイクルを完了するのに少なくとも 6 か月かかります。

  • 関数の戻り値の型を変更する必要がある場合は、新しい型を返す新しい関数を追加することを検討してから、古い関数を非推奨にする手順に従ってください。

  • タイプが原因で既存の可能性と区別できない新しい入力を受け入れる必要がある場合は、別のキーワード引数で渡すことを検討するか、新しい形式のみを受け入れる 2 番目の関数を追加します。

非推奨警告の発行#

The proper way to raise a deprecation warning is to use the decorators @deprecate_arg and @deprecate_func from qiskit.utils.deprecation. These will generate a standardized message and and add the deprecation to that function’s docstring so that it shows up in the docs.

from qiskit.utils.deprecation import deprecate_arg, deprecate_func

@deprecate_func(since="0.24.0", additional_msg="No replacement is provided.")
def deprecated_func():
    pass

@deprecate_arg("bad_arg", new_alias="new_name", since="0.24.0")
def another_func(bad_arg: str, new_name: str):
    pass

Usually, you should set additional_msg: str `` with the format ``"Instead, use ..." so that people know how to migrate. Read those functions』 docstrings for additional arguments like pending: bool and predicate.

If you are deprecating outside the main Qiskit repo, set package_name to match your package. Alternatively, if you prefer to use your own decorator helpers, then have them call add_deprecation_to_docstring from qiskit.utils.deprecation.

If @deprecate_func and @deprecate_arg cannot handle your use case, consider improving them. Otherwise, you can directly call the warn function from the warnings module in the Python standard library, using the category DeprecationWarning. For example:

import warnings

def deprecated_function():
    warnings.warn(
        "The function qiskit.deprecated_function() is deprecated since "
        "Qiskit Terra 0.20.0, and will be removed 3 months or more later. "
        "Instead, you should use qiskit.other_function().",
        category=DeprecationWarning,
        stacklevel=2,
    )
    # ... the rest of the function ...

非推奨の警告を導入したパッケージのバージョンを必ず含めてください (メンテナーがそれを削除することが有効な時期を簡単に確認できるようにするため)、および代替パスが何であるかを確認してください。

stacklevel 引数に注意してください。 これは、非推奨であると非難される関数を制御します。 stacklevel=1 (デフォルト) を設定すると、警告は warn 関数自体を非難し、stacklevel=2 はそれを含む関数を正しく非難することを意味します。 これを 2 以外に設定することはまれですが、ヘルパー関数を使用して複数の場所で同じ警告を発行する場合に役立ちます。

非推奨機能のテスト#

非推奨の警告を追加するたびに、機能に関連するテストを更新する必要があります。 それ以外の場合、新しい警告により、テスト スイートは失敗するはずです。 廃止された機能が引き続き機能することを確認するために、廃止期間を通じて廃止された機能を引き続きテストする必要があります。

テストを更新するには、非推奨の動作の各呼び出しを独自のアサーション ブロックでラップする必要があります。 unittest.TestCase (すべての Qiskit テスト ケース) のサブクラスの場合、これは次のように行われます。

class MyTestSuite(QiskitTestCase):
   def test_deprecated_function(self):
      with self.assertWarns(DeprecationWarning):
         output = deprecated_function()
      # ... do some things with output ...
      self.assertEqual(output, expected)

非推奨および破壊的変更の文書化#

It is important to warn the user when your breaking changes are coming.

@deprecate_arg and @deprecate_func will automatically add the deprecation to the docstring for the function so that it shows up in docs.

If you are not using those decorators, you should directly add a Sphinx deprecated directive

.. code-block:: python
def deprecated_function():

「」」 Short description of the deprecated function.

バージョン 0.20.0 で非推奨: The function qiskit.deprecated_function() is deprecated since Qiskit Terra 0.20.0, and will be removed 3 months or more later. Instead, you should use qiskit.other_function().

<rest of the docstring> 「」」 # … the rest of the function …

You should also document the deprecation in the changelog by using Reno. Explain the deprecation and how to migrate.

In particular situations where a deprecation or change might be a major disruptor for users, a migration guide might be needed. Once the migration guide is written and published, deprecation messages and documentation should link to it (use the additional_msg: str argument for @deprecate_arg and @deprecate_func).