관리자 가이드¶

이 문서는 관리자 를 병합 권한을 가진 기여자로 정의한다. 여기에 자세히 설명된 정보는 주로 Qiskit 배포 및 기타 내부 과정과 관련된 것이다.

안정된 브랜치 정책¶

안정된 브랜치는 배포 후 마스터에서 수정된 심각한 버그 및 보안 이슈에 대한 안전한 소스를 유지하는 것을 목표로 한다. 안정된 브랜치의 PR을 검토할 땐, 주어진 패치의 위험과 안정된 브랜치의 사용자에게 제공할 가치 사이의 균형을 맞춰야 한다. 안정된 브랜치에는 한정된 클래스의 변경만 포함하는 것이 적절하다. 상당히 모호한 오류 처리 사례에 대한 사소한 수정과 같이, 주요 이슈에 대한 크고 위험한 패치가 유효한 경우도 있다. 변경을 고려할 때, 다음과 같은 여러 요소를 고려해야 한다:

회귀의 위험: 아주 작은 변경도 무언가를 망가트릴 위험이 있으며, 안정된 브랜치에서는 최대한 회귀를 제고하고자 한다.
사용자 가시성 이점: 사용자가 실제로 알아차릴 만한 것을 수정하는가? 그렇다면 그것은 얼마나 중요한가?
수정이 얼마나 자립적인가: 중요한 문제를 해결하지만 동시에 많은 코드를 변경하는 경우, 덜 위험한 수정은 어떤 모습일지 생각해볼 가치가 있다.
수정 사항이 이미 마스터 브랜치에 있는가: 수정 사항이 마스터 브랜치에 적합하지 않은 경우가 아니라면, 수정 사항은 이미 마스터 브랜치에 병합된 이전 버전을 수정하는 백포트(backport)여야 한다.

백포팅 절차:¶

마스터에서 안정적인 패치로 백포팅할 때 마스터의 변경 사항에 대한 참조를 유지하려고 한다. 브랜치에 안정적인 PR을 만드는 경우 다음 명령어를 사용한다:

$ git cherry-pick -x $master_commit_id

아지만 이것은 마스터의 작은 자체 포함 패치에만 작동한다. 마스터에서 더 큰 커밋(예: squashed PR에서)의 하위 집합을 백포트해야 하는 경우 수동으로 진행한다. 이러한 경우 다음을 추가 한다.

Backported from: #master pr number

특별히 선별된 내용이 의미가 통하지 않더라도 변경된 부분의 원래 소스 코드를 추적할 수 있다.

새롭게 제안하는 패치가 정확히 선별하지 않더라도 스스로 상충되는 부분을 해결하고, 결과로 초래된 패치를 제안함으로써 도움을 줄 수 있다. 안정된 패치의 검토를 돕기 위해서 커밋 메시지에 상충됨(Conflicts) 을 표시하기 바란다.

이전 버전을 수정하는 백포트(backport) 라벨들¶

잠재적인 안정된 백포트(stable backport potential) 로 태그된 버그나 풀 리퀘스트는 안정된 릴리즈에 적용되는 버그이며, 마스터 브랜치에 머지되는 순간 이전 버전을 수정하는 백포트(backport) 로써 적합할 수 있다. 백포트가 제안되면, 해당 태그는 제거되어야 한다.

대상 브랜치를 안정되었다고 설정하는 표시는 실수가 아니기 때문에 안정된 브랜치에 대한 PR의 제목에는 [Stable] 을 포함시킨다. 또한, 마스터 브랜치에 머지된 PR 참조번호를 추가한다.

Qiskit 버저닝(Versioning)¶

Qiskit 프로젝트는 각각 다른 기능을 수행하는 여러 요소들로 구성되어 있다. 각각은 독립적으로 유용하고 사용될 수 있으나, 편의상 저장소와 모든 요소를 한 번에 설치할 수 있는 단일 진입점을 제공하는 메타-패키지를 제공한다. 이는 설치 과정을 간소화하고 사용자에게 통일된 인터페이스를 제공하기 위함이다. 하지만 각 Qiskit 요소들은 자신들만의 배포 버전을 가지고 있기 때문에 다른 저장소의 버전을 다룰 때에는 주의가 필요하다. 이 문서는 Qiskit 요소와 메타-패키지의 배포 버전을 다룰 때의 지침을 설명한다.

이 지침의 남은 부분에서 표준 유의적 버전(Semantic Versioning) 명명법은 서로 다른 버전을 Major.Minor.Patch 으로 표기할 것이다. 예를 들어 버전 번호가 0.7.1 라면, 주 버전(major version)은 0, 부 버전(minor version)은 7, 그리고 패치 버전(patch version)은 1 이다.

메타-패키지 버전¶

Qiskit 메타-패키지 버전은 독립적인 값으로 각각의 요소들의 배포 버전에 따라 결정된다. 추적되는 요소 (혹은 새로운 요소를 추가하거나) 를 메타-패키지의 필요 항목에 푸시(push)할 때마다 버전은 갱신되어야 하고 새 배포가 발행된다. 메타-패키지 배포가 각 요소의 배포 버전과 일치하도록 발행 일정을 조율한다.

새 추적 요소 추가하기¶

새로운 Qiskit 요소가 메타-페키지 필요 항목에 추가되면, 메타-패키지의 부 버전을 올려야 한다.

예를 들어, 메타 패키지가 qiskit-aer 및 qiskit-terra 요소 2개를 추적하고 있고 해당 버전이 0.7.4 인 경우를 살펴 보자. 그런 다음 메타 패키지에도 포함시키려는 새로운 요소 qiskit-new 를 릴리즈 한다. 메타 패키지에 새 요소를 추가할 때 버전을 0.8.0 으로 늘린다.

패치 버전 증가¶

메타-패키지에서 추적 중인 Qiskit 요소가 버그를 고치고자 패치 버전을 공개했다면, setup.py 파일에 있는 필요 항목을 고치고 메타-패키지의 패치 버전을 증가시켜야 한다.

예를 들어, 메타 패키지가 2개의 요소 qiskit-terra==0.8.1 및 qiskit-aer==0.2.1 를 추적하며 현재 버전은 0.9.6 인 경우를 살펴보자. qiskit-terra가 버그 0.8.2 를 수정하기 위해 새 패치 버전을 출시할 때 메타 패키지도 패치 버전과 릴리스를 늘려 0.9.7 이 되어야 한다.

추가로, 가끔은 패키징이나 메타-패키지 자체의 다른 버그로 이를 고치고 새 버전을 출시해야 할 수 있다. 이러한 상황에서는 잘못된 배포에서 구분되도록 패치 버전을 증가시켜야 한다. 어떤 경우에서도 pypi의 오래되거나 잘못된 배포를 지우지 말고, 대신에 패치 버전을 올리고 새 배포를 업로드하라.

부 버전 증가¶

메타-패키지에 새로운 요소를 추가하는 것 외에도 추적되는 요소의 부 버전이 증가할 때마다 메타-패키지의 부 버전도 증가해야 한다.

예를 들어, 메타-패키지가 2개의 요소 qiskit-terra==0.7.0 과 qiskit-aer==0.1.1 을 추적하고 버전이 0.7.5 라고 해보자. qiskit-aer 요소가 0.2.0 버전을 공개했다면 메타-패키지 버전도 0.8.0 로 올려서 새 배포에 일치시켜야 한다.

주 버전 증가¶

주 버전은 다른 버전 숫자들과는 다르다. 각각의 추적되는 요소에 맞춰 갱신되는 다른 버전 숫자들과는 달리 주 버전은 모든 추적되는 버전이 새 버전으로 올라갈 때 (적어도 1.0.0 전에) 에만 증가하게 된다. 현재는 모든 요소의 주 버전이 아직 0 이고 메타-저장소에 있는 각각의 추적 요소들이 안정적으로 판단되어 주 버전이 >=1 이 되기 전까진 메타-페키지의 주 버전을 올리지 않는다.

모든 요소들이 >=1.0.0일 때 주 버전 숫자가 어떻게 바뀌어야 할 지에 대해서는 아직 정해지지 않았다.

추가 옵션¶

추적되는 요소 외에도 Qiskit과 함께 개발된 Qiskit 위에 설치되는 추가 패키지가 있으며, 예를 들어 qiskit-optimization과 같은 응용 프로그램 저장소가 있다. 편의성을 위해 이 패키지들은 Qiskit과 함께 설치될 수 있는 선택 사양으로써 Qiskit 메타-패키지에 추적된다. 이러한 다운스트림 프로젝트들의 배포는 메타-패키지 배포를 유도하지 않으며 메타-패키지 버전에도 영향을 주지 않는다. 만약 Qiskit과 해당 다운스트림의 선택적 종속성 사이에서 호환성 문제가 있어서 독립적 배포의 최소 버전이 조정되어야 하는 경우, 패키지 버그 수정처럼 패치 버전 배포로만 되어야 한다.

Qiskit 요소 요구사항 추적¶

메타-패키지와 Qiskit 버저닝과 엄밀하게 관련되어 있는 건 아니지만, 메타-패키지의 요구사항 목록에 있는 요소 버전을 추적하는 것은 중요하다. setup.py 에 나열된 각각의 요소들은 단일 버전으로 고정되어 있어야 한다. 이는 Qiskit의 각 버전이 추적되는 요소 중에서 단일 버전만 설치해야 한다는 것을 의미한다. 예를 들어서, 어떤 순간에서의 요구사항 목록은 다음과 같이 보일 것이다:

requirements = [
    "qiskit_terra==0.7.0",
    "qiskit-aer==0.1.1",
]

이것은 디버깅을 돕기 위한 것이지만, 여러 요소들 간에 버전을 추적하는 일을 더 투명하도록 해 준다.

문서 구조¶

Qiskit에서 문서가 조직된 방식은 가능한 많은 문서를 docstring으로 입력하는 것이다. 이 방식은 문서 자체가 코드와 함께 존재하기 때문에 개발 과정에서 문서를 추가하거나, 수정하는 것을 쉽게 만든다. Terra의 일반적인 문서 구조에는 세 개의 레벨이 있다:

docs/apidocs 에 위치한 .rst 파일들

These files are used to tell Sphinx which modules to include in the rendered documentation. This contains two pieces of information: an internal reference or cross reference to the module, which can be used for internal links inside the documentation, and an automodule directive used to parse the module docstrings from a specified import path. For example, the dagcircuit.rst file contains:

.. _qiskit-dagcircuit:


.. automodule:: qiskit.dagcircuit
   :no-members:
   :no-inherited-members:
   :no-special-members:

이런 형식과 다른 유일한 .rst 파일은 목차를 포함하는 qiskit.rst 이다. 새로운 모듈의 문서에 대한 .rst 파일을 추가한다면, 해당 파일에 toctree 을 추가해야 한다.

모듈-레벨 docstring

이 docstring은 rst 파일의 automodule 지시자에 명시된 모듈에 대한 모듈 레벨에 있다. 명시된 모듈이 디렉토리/명칭 공간라면, docstring은 그 디렉토리의 __init__.py 에 명시되어야 한다. 이 모듈-레벨의 docstring은 문서화된 모듈에 대한 더 많은 세부정보를 포함한다. 이 docstring의 일반적인 구조는 모듈에 포함된 공개 API의 모든 클래스와 함수를 나열하는 것이다. 이는 일반적으로 autosummary directive 에 의해서 실행된다(또는 qiskit.execute 의 경우와 같이 모듈이 간단한 경우에는 autodoc directives 로 직접 실행). autosummary directive는 다른 Python 요소들(클래스, 함수 등)을 각각의 autodoc directive를 호출할 필요 없이 직접 이런 요소들의 autodoc을 실행하는데 사용된다. 모듈-레벨 docstring은 모듈이 제공하는 기능에 대한 높은 수준의 개요를 제공한다. 이는 주로 공개 API의 다른 컴포넌트를 여러 세부항목으로 묶음으로서 이루어진다.

예를 들어, 이전에 제시된 dagcircuit 모듈 예제에서 qiskit/dagcircuit/__init__.py 에 대한 모듈 docstring의 내용은 다음과 같을 것이다:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================

.. currentmodule:: qiskit.dagcircuit

DAG Circuits
============

.. autosummary::
   :toctree: ../stubs/

   DAGCircuit
   DAGNode

Exceptions
==========

.. autosummary::
   :toctree: ../stubs/

   DAGCircuitError
"""

참고

이것은 예일 뿐이며 dagcircuit 회로 모듈에 대한 실제 모듈 문서 문자열은 이와 다를 수 있다.

모듈 docstring에 나열된 요소들에 대한 실제 docstring

개발자들은 필요한 경우에 예제를 사용하여 노출된 모든 공개 인터페이스를 철저하게 문서화하기위해 노력해야 한다. docstring은 Google Python 스타일 Docstring 이 사용된다. 이후 문서는 napoleon sphinx 확장판 을 사용하여 분석된다. napoleon 문서 는 docstring이 어떻게 형식화되어야 하는지에 대한 좋은 예제를 포함한다.

참고

필요한 곳에 Sphinx나 rst 포맷형식을 사용할 수 있다. 예를 들어, 한 가지 공통적으로 사용되는 확장은 jupyter-execute 지시자이며, 이는 주피터(Jupyter) 에서 코드 블록을 실행하고, 코드와 결과를 보여주는데 사용된다. 이는 시각화에 특히 매우 유용하다.

문서 통합¶

https://qiskit.org/documentation/ 에서 제공하는 문서는 전체 Qiskit 프로젝트를 다룬다. Terra는 그 중 하나에 해당한다. 따라서 제공되는 문서 빌드 버전은 Qiskit 메타-패키지 저장소 https://github.com/Qiskit/qiskit 를 따른다. 커밋이 해당 저장소로 병합되면, Sphinx 빌드의 결과물이 qiskit.org 웹사이트에 전송된다. 이 Sphinx 빌드는 그 시점의 메타-패키지로 설치된 Qiskit 요소의 버전으로 문서로 구성된다. 예를 들어, 메타-패키지의 현재 버전이 0.13.0이면 이는 Terra의 0.10.0 릴리즈에서 문서를 가져올 것이다. 메타-패키지의 요구사항이 서로 충돌하는 경우, 새 버전에서 문서를 가져올 것이다. 이는 잘못된 API 문서의 수정 사항들이 새 릴리즈에 포함될 필요가 있음을 의미한다. 문서 수정은 안정된 브랜치 정책 ( 안정된 브랜치 정책 을 보라) 마다 안정된 패치 릴리즈에 대한 적합한 백포트이다.

빌드 과정에서 각 요소의 docs/apidocs/ 내용은 모든 다른 요소와 함께 메타-패키지 저장소에 있는 doc/apidocs/ 의 공유된 복사본에 반복적으로 복사된다. 이렇게 함으로써, 릴리즈의 각 요소에서 docs/apidocs의 최상위에 있는 것은 https://qiskit.org/documentation/apidoc/의 최상위에 있게 된다.