メンテナーガイド¶

このドキュメントでは、 メンテナー をマージ権限を持つ貢献者として定義しています。ここで詳しく説明する情報は、主にQiskitのリリースやその他の内部プロセスに関連しています。

ブランチの安定化ポリシー¶

安定ブランチは、リリース後にマスター上で修正された、影響の大きいバグやセキュリティー問題に対応する修正の安全なソースになることを目的としています。安定ブランチのプルリクエスト(PR) をレビューする時、与えられたパッチのリスクと安定ブランチの価値のバランスを取る必要があります。安定ブランチへの取り込みは、限定されたクラスのみの変更が適しています。大きな問題に対する大きくリスクの高いパッチは、あまり目立たないのエラー処理のための些細な修正同様、理にかなっているかもしれません。変更をレビューする際には、多くの要因を検討する必要があります。

リグレッションのリスク: 最も小さな変更でも何かを壊すリスクがあり、stableブランチ上でのリグレッションは本当に避けたいです。
ユーザーに見える利益: ユーザーが本当に気が付く修正していますか？そうであれば、その重要性はどのくらいですか？
修正の自己完結度:　重要な問題を修正するだけでなく多くのコードをリファクタリングしている場合は、リスクの低い修正がどのようなものになるかを検討する価値があると考えられます。
修正がすでにマスターブランチにあるかどうか: 変更がマスターに対して意味を持っていない場合、変更は既にマスターにマージされた変更のバックポートでなければなりません。

バックポーティングの方法¶

マスターから安定ブランチへパッチをバックポーティングする際には、マスター上の変更の参照を保持します。安定したプルリクエスト(PR) のブランチを作成する場合、以下を使用して下さい:

$ git cherry-pick -x $master_commit_id

ただし、これはマスターからの小さな自己完結型パッチのみに対応しています。マスターから、より大きなコミットのサブセット (例えば、squashされた PRなど) をバックポートする必要がある場合は、手動で行います。このような場合には、以下を追加します:

Backported from: #master pr number

そうすれば、厳格なcherry-pickの意味が分からなくても、変更サブセットのソースを追跡できるようになります。

提案するパッチがきれいにcherry-pickしない場合は、競合を自分で解決し、その結果のパッチを提案することができます。安定したパッチのレビューをサポートするために、コミット・メッセージ内の競合行を保持してください。

バックポート・ラベル¶

stable backport potential とタグ付けされたバグやプルリクエスト (PR) は、安定したリリースにも適用されるバグであり、マスターの一時修正が行われると、バックポーティングに適している可能性があります。バックポートが提案されると、タグを削除する必要があります。

ターゲット・ブランチを安定と設定したことが間違いないようにするために、安定ブランチに対するプルリクエスト (PR) のタイトルに [Stable] を含めて下さい。また、ポーティングしているマスター中のプルリクエスト (PR) 番号を参照して下さい。

Qiskit バージョン管理¶

Qiskitプロジェクトは、それぞれが異なる機能を実行するいくつかの要素で構成されています。それぞれが独立して有用であり、単独で使用できますが、便宜上、このリポジトリとメタパッケージを提供して、すべての要素を一度にインストールするための単一のエントリポイントを提供します。これは、インストールプロセスを簡素化し、エンドユーザーに統一されたインターフェイスを提供するためです。ただし、各Qiskit要素には独自のリリースとバージョンがあるため、異なるリポジトリ間でバージョンを処理する場合は注意が必要です。このドキュメントでは、Qiskit要素とメタパッケージの両方のバージョンとリリースを処理するためのガイドラインの概要を説明します。

このガイドの残りでは、異なるコンポーネントのバージョン番号を参照するのに、標準のセマンティックバージョニング (Semantic Versioning) 命名規則: Major.Minor.Patch を採用します。例えば、バージョン番号が 0.7.1 だった場合、メジャーバージョンは 0 、マイナーバージョンが 7、そしてパッチバージョンが 1 です。

メタパッケージバージョン¶

Qiskitメタパッケージバージョンは、追跡対象の各要素のリリースによって決定される独立した値です。リリースを追跡対象コンポーネントにプッシュする(または要素を追加する)たびに、メタパッケージの要件とバージョンを更新し、新しいリリースを公開する必要があります。タイミングを要素のリリースと調整して、メタパッケージのリリースが要素のリリースを追跡するようにします。

新しい追跡要素の追加¶

新しいQiskit要素がメタパッケージ要件に追加されると、メタパッケージのマイナーバージョンを増やす必要があります。

たとえば、メタパッケージが2つの要素 qiskit-aer と qiskit-terra を追跡しており、そのバージョンが 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の各バージョンでは、追跡対象の要素ごとに1つのバージョンのみをインストールする必要があります。たとえば、特定の時点での要件リストは次のようになります。

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

これはデバッグに役立つだけでなく、複数の要素にわたるバージョンの追跡をより透明にするためでもあります。

文書構造¶

The way documentation is structured in Qiskit is to push as much of the actual documentation into the docstrings as possible. This makes it easier for additions and corrections to be made during development, because the majority of the documentation lives near the code being changed.

Refer to https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html for how to create and write effective API documentation, such as setting up the RST files and docstrings.

qiskit-metapackage repository¶

Historically, Qiskit Ecosystem projects were hosted at https://qiskit.org/documentation/. Those projects now live under https://qiskit.org/ecosystem and https://qiskit.org/documentation is only for core Qiskit (aka Terra).

While we finish this migration, documentation for Qiskit is still built in https://github.com/Qiskit/qiskit-metapackage. The metapackage will Git clone Terra to pull in its API documentation, using whatever version of Terra is pinned in the setup.py. This means that fixes for incorrect API documentation will need to be included in a new release. Documentation fixes are valid backports for a stable patch release per the stable branch policy (see ブランチの安定化ポリシー).

This setup is temporary and we are migrating the metapackage documentation infrastructure to live in Terra. See https://github.com/Qiskit/RFCs/issues/41 to track the migration.