Leitfaden für Maintainer¶

Dieses Dokument definiert einen Maintainer als einen Beitragenden mit Zusammenführungsrechten. Die hier beschriebenen Informationen beziehen sich hauptsächlich auf Qiskit-Releases und andere interne Prozesse.

Stable-Branch-Policy¶

Der Stable-Branch ist als sichere Quelle für die Behebung von schwerwiegenden Fehlern und Sicherheitsproblemen gedacht, die seit einem Release auf Master-Branch behoben wurden. Bei der Überprüfung eines PRs für den stabilen Branch müssen wir das Risiko eines jeden Patches gegen den Wert abwägen, den er für die Benutzer des stabilen Branchs hat. Nur eine begrenzte Anzahl von Änderungen ist für die Aufnahme in den stabilen Branch geeignet. Ein großer, riskanter Patch für ein großes Problem könnte Sinn machen, ebenso wie ein trivialer Fix eines Code-Branchs zur Behandlung von relativ selten auftretenden Fehlern. Bei einer Änderung muss eine Reihe von Faktoren abgewogen werden:

Das Risiko des Rückschritts: Selbst die kleinste Änderung bringt das Risiko mit sich, Fehler zu verursachen. Solche Rückschritte wollen wir auf dem Stable-Branch definitiv vermeiden.
Der Vorteil verbesserter Sichtbarkeit für Benutzer: Beheben wir etwas, was die Benutzer tatsächlich bemerken werden, und wenn ja, wie wichtig ist es?
Wie autark ist die Änderung: Wenn eine Änderung ein wichtiges Problem löst aber auch jede Menge Code überarbeitet, sollte man wahrscheinlich darüber nachdenken, wie ein weniger riskanter Fix aussehen könnte.
Gibt es die Korrektur bereits auf dem Master: Eine Änderung muss eine Rückportierung einer Änderung sein, die bereits auf dem Master zusammengeführt wurde, es sei denn, die Änderung ist auf dem Master einfach nicht sinnvoll.

Rückportierungsverfahren:¶

Bei der Rückportierung einer Änderung vom Master in den Stable-Branch, wollen wir eine Referenz auf die Änderung im Master-Branch behalten. Beim Erstellen des Branches für den Pull-Request verwendet man:

$ git cherry-pick -x $master_commit_id

Das funktioniert jedoch nur für kleine, in sich geschlossene Änderungen vom Master-Branch. Wenn man einen Teil eines größeren Commits (z. B. eines zusammengefassten Pull-Requests) vom Master rückportieren möchte, macht man dies manuell. In solchen Fällen fügt man dies hinzu:

Backported from: #master pr number

um die Quelle der Änderungen nachvollziehen zu können - selbst wenn ein cherry-pick nicht sinnvoll wäre.

Wenn ein Cherry-Pick des Patches, den man vorschlägt, nicht ohne Konflikte verläuft, kann man diese selbst beheben und dann den resultierenden Patch vorschlagen. Um die Prüfung des Stable-Branch zu vereinfachen, belässt man dabei die Conflicts-Zeilen in der Commit-Nachricht.

Backport-Labels¶

Bugs oder Pull-Requests, welche mit dem Label stable backport potential gekennzeichnet wurden, kommen für eine Rückportierung in den Stable-Branch in Frage, sobald dafür ein Patch im Master-Branch ist. Sobald die Rückportierung geplant ist, sollte das Tag entfernt werden.

Um zu zeigen, dass die Auswahl des Stable-Branch als Ziel eines Pull-Requests kein Fehler war, verwenden Sie [Stable] im Titel. Zusätzlich geben Sie eine Referenz zum Pull-Request der Änderung im Master-Branch an, welche Sie rückportieren.

Qiskit-Versionierung¶

Das Qiskit-Projekt setzt sich aus mehreren Elementen zusammen, die jeweils unterschiedliche Funktionen ausführen. Jedes ist unabhängig nutzbar und kann für sich alleine verwendet werden. Dieses Repository und Meta-Paket wird aus Gründen der Vereinfachung zur Verfügung gestellt, um einen einzelnen Startpunkt zur Verfügung zu stellen alle Elemente auf einmal zu installieren. Durch die Bereitstellung einer einheitlichen Schnittstelle für die Endnutzer wird der Installationsvorgang vereinfacht. Da jedes Qiskit-Element seine eigenen Releases und Versionen hat, ist jedoch eine gewisse Pflege erforderlich, wenn es um Versionen zwischen den verschiedenen Repositorys geht. In diesem Dokument werden die Richtlinien für den Umgang mit Versionen und Releases von Qiskit-Elementen und dem Meta-Paket beschrieben.

Für den Rest dieses Handbuchs wird die Standardnomenklatur Semantic Versioning verwendet werden: Major.Minor.Patch, um auf die verschiedenen Komponenten einer Versionsnummer zu verweisen. Wenn z. B. die Versionsnummer 0.7.1 ist, dann ist die Hauptversion 0, die Nebenversion 7 und die Patch-Version 1.

Meta-Paketversion¶

Die Metapaket-Version von Qiskit ist eine unabhängigere Einheit, die von den Releases der einzelnen Elemente bestimmt wird. Jedes Mal, wenn wir ein Release zu einer Tracking-Komponente bringen (oder ein Element hinzufügen) müssen die Meta-Paketanforderungen und Version aktualisiert, und ein neues Release veröffentlicht werden. Der Zeitpunkt sollte mit der Veröffentlichung von Elementen koordiniert werden, um sicherzustellen, dass die Meta-Paket-Releases mit den Elementversionen übereinstimmen.

Neue Elemente hinzufügen¶

Wenn ein neues Qiskit-Element zu den Meta-Paket-Anforderungen hinzugefügt wird, müssen wir die ** Minor** Version des Meta-Pakets erhöhen.

Beispiel: Ein Meta-Paket mit 2 Elementen qiskit-aer und qiskit-terra und der Version 0.7.4. Nun wird ein neues Element qiskit-neu veröffentlicht, das dann auch in das Meta-Paket aufgenommen werden soll. Wenn dieses neue Element zu dem Meta-Paket hinzugefügt wird, erhöht sich die Version auf 0.8.0.

Patch-Version erhöhen¶

Wenn ein Qiskit-Element, das bereits vom Meta-Paket verfolgt wird, eine Patch-Version veröffentlicht, um Fehler in einem Release zu beheben, müssen wir auch die Anforderung im setup.py anpassen und dann die Patch-Version des Meta-Pakets erhöhen.

Wenn zum Beispiel das Meta-Paket 2 Elemente qiskit-terra==0.8.1 und qiskit-aer==0.2.1 mit der aktuellen Version 0.9.6 verfolgt. Wenn qiskit-terra eine neue Patch-Version veröffentlicht, um einen Fehler 0.8.2 zu beheben. dann muss das Meta-Paket auch seine Patch-Version und -Veröffentlichung erhöhen und wird zu 0.9.7.

Zusätzlich gibt es gelegentlich Pakete oder andere Fehler im Meta-Paket selbst, die durch Veröffentlichung neuer Releases behoben werden müssen. Wenn diese aufgetreten sind, soll die Patchversion erhöht werden, um sie von der defekten Version zu unterscheiden. Defekte oder alte Versionen von pypi sollen nicht gelöscht werden. Stattdessen soll die Patch Version erhöht und eine entsprechend höhere Version hochgeladen werden.

Geringfügige Versionserhöhungen¶

Neben dem Hinzufügen eines neuen Elements zum Meta-Paket sollte auch die Nebenversion des Meta-Pakets erhöht werden, wenn eine Nebenversion in einem überwachten Element erhöht wird.

Zum Beispiel, wenn das Meta-Paket 2 Elemente qiskit-terra == 0.7.0 `` und ``qiskit-aer == 0.1.1 `` und die aktuelle Version ``0.7.5 verfolgt. Wenn das `` qiskit-aer `` -Element 0.2.0 freigibt, müssen die Meta-Paket-Version auf 0.8.0 erhöht werden, um dem neuen Release zu entsprechen.

Eine Erhöhung der Hauptversion¶

Die Hauptversion unterscheidet sich von den anderen Versionen. Im Gegensatz zu den anderen Versionen, die unmittelbar mit jedem verfolgten Element aktualisiert werden, wird die Hauptversion nur erhöht, wenn alle verfolgten Versionen abgestoßen werden (mindestens vor „1.0.0“). Im Moment haben alle Elemente noch eine Hauptversionsnummernkomponente von „0“ und bis jedes verfolgte Element im Meta-Repository als stabil markiert wird, indem die Hauptversion auf „> = 1“ gesetzt wird, sollte die Meta-Version die Paketversion der Hauptversion nicht erhöhen.

Das Verhalten der Haupt-Versionsnummer-Komponentenverfolgung, nachdem alle Elemente bei >=1.0.0 liegen, wurde noch nicht entschieden.

Optionale Extras¶

Zusätzlich zu den verfolgten Elementen gibt es zusätzliche Pakete, die auf Qiskit aufgebaut sind, die im Tandem mit Qiskit entwickelt werden, zum Beispiel die Anwendungsrepositorys wie qiskit-optimization. Für den Komfort werden diese Pakete mit dem Qiskit-Metapaket als optionale Extras nachgeführt, die mit Qiskit installiert werden können. Die Releases dieser optionalen Downstream-Projekte lösen kein Metapaket-Release aus, da sie nicht gepinnt werden und die Metapaketversion nicht beeinflussen. Wenn es ein Kompatibilitätsproblem zwischen Qiskit und diesen nachgelagerten optionalen Abhängigkeiten gibt und die Mindestversion in einem eigenständigen Release angepasst werden muss, wird dies nur als Patch-Version-Release ausgeführt, da es sich dabei um ein ‚packaging bugfix‘ handelt.

Qiskit-Element-Anforderungs-Tracking¶

Obwohl kein strenger Zusammenhang mit dem Meta-Paket und der Qiskit-Versionierung besteht, ist es wichtig, wie wir die Element-Versionen in den Voraussetzungen des Meta-Pakets tracken. Jedes Element, das im setup.py aufgeführt ist, sollte auf eine einzige Version angeheftet werden. Dies bedeutet, dass jede Version von Qiskit nur eine einzige Version für jedes überwachte Element installieren sollte. Die Liste an Voraussetzungen an einem beliebigen Punkt sollte beispielsweise wie folgt aussehen:

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

Dies soll beim Debuggen helfen, aber auch den Überblick über die Versionen mehrerer Elemente transparenter machen.

Aufbau der Dokumentation¶

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 Stable-Branch-Policy).

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.