지원 중단 정책#

많은 사용자 및 기타 패키지들은 Qiskit의 다른 부분에 의존한다. 따라서 코드를 변경할 때마다 사용자가 이미 작성한 코드를 손상시키지 않고 수정할 수 있는 충분한 시간을 제공해야 한다.

가장 중요한 것: 피할 수 없는 경우가 아니면 공개 인터페이스를 변경하지 않는다. 간단한 아이템을 추가하는 것은 괜찮지만, 아이템을 삭제하는 것은 사용자에게 번거로운 일이지만 충분히 공지하여 합리적으로 처리할 수 있다. 하지만 일반적으로 코드가 작동하는 방식을 변경하면 사용자가 두 가지 후속 버전의 Qiskit에서 작동하는 코드를 작성할 수 없으므로 허용되지 않는다.

사용자들이 종종 Qiskit 코드 개발자들이 내부적이거나, 널리 사용되지 않는 기능이라 생각하는 클래스 및 메소드를 사용한다는 점에 주의한다. “이것은 잘 보이지 않으니 사용자가 없을 것이다”라고 가정하면 안된다. 코드나 함수가 공개된 경우는 모두 정책의 적용 대상이 된다. 유일한 예외는 명시적으로 내부에 있는 함수와 모듈로, 즉 이름이 밑줄로 시작하는 것(_)들 이다.

지침은 다음과 같다.

  • 최소 3개월 또는 2회의 완전한 버전 주기 동안 적극적으로 경고한 후 코드를 제거하거나 변경한다.

  • 경고를 발생시키지 않고 원하는 기능을 구현하기 위한 방법을 항상 마련되어야 한다.

  • 명시적으로 내부적이지 않은 함수들도 사용되고 있을 수 있음을 가정한다.

  • 모든 사용 중단, 변경 및 제거는 API 변경으로 간주되며 안정적인 브랜치 정책 에 따라 패치 릴리스가 아닌 마이너 릴리스에서만 발생할 수 있다.

기능의 제거#

기능(예: 클래스, 함수 또는 함수 매개변수) 을 제거할 때에는 다음의 절차를 따른다.

  1. 경고를 이슈로 발행하기 전에 하나의 마이너 버전에 대한 대체 경로가 있어야 한다 . 예를 들어, foo() 함수를 bar() 로 교체하려면 foo() 내에서 경고를 발생시키기 전에 두 함수 모두를 사용하여 최소한 한 번 릴리스해야 한다. 이전 브랜치에서 즉시 PendingDeprecationWarning을 실행시킨다.

    이유: 사용자들에게 버젼이 업그레이드된 직 후, 코드를 훼손하지 않고 교체할 시간을 줄 필요가 있다.

  2. 최소한 하나의 마이너 버전에 대한 대체 경로가 설정되면 issue the deprecation warnings 를 발행한다. 더 이상 사용되지 않는 경로, 해당 대안 및 사용 중단 이유를 나열하는 deprecations 섹션이 있는 릴리스 노트를 추가한다. Update the tests to test the warnings 경고를 테스트하기 위해 테스트를 업데이트 한다.

    이유: 버젼 이동이 발생했을 때 사용자의 충격을 최고화 하기 위해 제거는 최소한 하나의 버전에서 잘 공지되고 사용자에게 알려져야 한다.

  3. 이전 기능의 제거 날짜를 설정하고 도달하면 제거(및 경고)한다. 제거 날짜는 경고가 있는 버전이 처음 릴리스된 후 최소 3개월 이후이어야 하며 경고 직후의 마이너 버전이 될 수 없다. 모든 제거를 나열하는 upgrade 릴리스 노트를 한다. 예를 들어, 대체 경로가 0.19.0 에 제공되고 경고가 0.20.0 에 추가된 경우, 0.21.0 이 0.20.0 이 발표된 후 3개월 이후에 발표 되었다고 하더라도, 대상이 실질적으로 제거될 가장 빠른 버전은 0.22.0 이 된다.

    참고

    이것은 최소 요구사항 이다. 중요하거나 핵심적인 기능을 제거하려면, 제공이 중단되기 전 사용자에게 최소한 추가적인 마이너 버전을 제공한다.

    이유 : 사용자에게 경고를 확인 한 후 적응할 시간을 제공한다. 모든 사용자가 Qiskit 버전을 최신으로 유지하는 것은 아니며 일부는 마이너 버젼들을 건너뛰기도 한다.

특정 기능이 사용 중지로 표기되면 제거 준비가 진행되지만, 사용자는 여전히 이 기능을 사용해 작업할 수 있어야 한다. “deprecated”로 표시된 기능은 더이상 업데이트되지 않고 고정된 것으로 간주한다. 따라서 제거될 때까지는 기능을 유지하기 위해 치명적인 버그 수정등은 유지하지만, 기능에 새로운 기능을 추가하지는 않는다.

변경 작업#

제거하지 않고 작동 방식을 변경하는 것은 특히 관리하기 어려운데, 두 가지 버전에 대해 두 가지 옵션을 모두 사용할 수 있어야 하고 경고를 발행시켜야 하기 때문이다. 예를 들어, 함수에서 반환 값의 유형을 변경하는 것은 거의 예외 없이 API 중단을 동반하게 되며, 이는 사용자들이 Qiskit을 사용하기 어렵게 만들고 곤란함을 겪에 만든다.

가장 좋은 해결책은 종종 새로운 기능을 만든 다음 위의 the procedures for removal 를 따르는 것이다.

기존 코드의 동작을 절대적으로 변경해야 하는 경우(버그 수정 제외) 이 문서의 맨 위에 있는 지침 원칙을 적용하기 위해 최선의 판단을 내려야 한다. 작동 방식의 변화에 대한 가장 적절한 경고는 일반적으로 FutureWarning 이다. 변경을 적용하는 방법에 대한 몇 가지 가능성은 다음과 같다:

  • 함수의 기본 동작을 변경하는 경우 키워드 인수를 추가하여 이전 동작과 새 동작 중에서 선택하는 것이 좋다. 배포할 시기가 다가왔을 때, 키워드 인수가 지정되지 않은 경우(예: None 인 경우) FutureWarning 을 발행하여 새 값이 곧 기본값이 되도록 설정할 수 있다. 동작을 변경한 후 이 키워드 인수를 제거하려면 일반적인 사용 중단 기간을 거쳐야 한다. 두 주기를 모두 거치는 데 최소 6개월이 소요된다.

  • 함수의 반환 유형을 변경해야 하는 경우 새 유형을 반환하는 새 함수를 추가한 다음 이전 함수 사용 중단 절차를 따른다.

  • 유형 때문에 이미 존재할 확률이 있는 입력과 구별할 수 없는 새 입력을 받아 들여야 하는 경우 다른 키워드 인수로 전달되도록 하거나 새 형식만 수락하는 두 번째 함수를 추가한다.

사용 중단 경고 발생#

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 이외의 값으로 설정하는 것은 드문 일이지만 도우미 기능을 사용하여 여러 위치에서 동일한 경고를 발행하는 경우 유용할 수 있다.

사용 중지된 기능의 테스트#

사용 중단 경고를 추가할 때마다 기능과 관련된 테스트를 업데이트해야 한다. 그렇지 않으면 새로운 경고 때문에 일련의 테스트 들이 실패하게 된다. 사용 중단 기간 동안 사용 중단된 기능을 계속 테스트하여 여전히 작동하는지 확인해야 한다.

테스트를 업데이트하려면 더 이상 사용되지 않는 동작의 각 호출을 자체 가정 설정문 블록(assertion block)으로 래핑해야 한다. 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)

Documenting deprecations and breaking changes#

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).