An Qiskit mitwirken¶

Qiskit ist ein Open-Source-Projekt mit dem Ziel Menschen aller Alters- und Berufsgruppen die Nutzung von Quanteninformationstechnologien zu ermöglichen. Diese Seite beschreibt wie man sich der Qiskit-Gemeinschaft anschließen kann.

Wo sich die Qiskit-Bestandteile befinden¶

Der Qiskit Quellcode befindet sich in dem Qiskit-Github-Repository. Dort können die einzelnen Bestandteile die Qiskit ausmachen gefunden werden. Unter anderem sind dies

Erste Schritte¶

Erfahren wie Mitglieder der Qiskit-Gemeinschaft

Bugs melden und Verbesserungen vorschlagen¶

Falls ein Problem auftritt, sollte ein Issue im entsprechenden Issue-Tracker eröffnet werden:

Element	Issue-Tracker
qiskit-terra	https://github.com/Qiskit/qiskit-terra/issues
qiskit-aer	https://github.com/Qiskit/qiskit-aer/issues
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/issues
Dokumente oder Qiskit Meta-Pakete	https://github.com/Qiskit/qiskit/issues

Falls man eine Idee für ein neues Funktion hat, sollte ein Enhancement-Issue im entsprechenden Issue-Tracker eröffnet werden. Wenn ein neues Issue eröffnet wird, wird eine Diskussion gestartet ob diese Idee in das Projekt passt, wie sie implementiert werden kann, etc.

Code Beisteuern¶

Styleguide¶

To enforce a consistent code style in the project, we use Pylint and pycodestyle to verify that code contributions conform to and respect the project’s style guide. To verify that your changes conform to the style guide, run: tox -elint

Contributor License Agreement (Mitwirkenden-Lizenzvereinbarung)¶

Bevor neuer Code beigesteuert werden kann müssen alle Mitwirkenden die „Contributer License Agreement“ (CLA) (Mitwirkenden-Lizenvereinbarung) unterscheiben. Mit dem Unterzeichnen der CLA bestätigt man, dass man Autor des Code-Beitrags ist, und dass man diesen unentgeltlich entsprechend der Apache-2.0 Lizenz beisteuert.

Wenn man an einem Qiskit-Projekt mit einem Pull-Request mitwirkt prüft ein Bot ob die CLA unterzeichnet wurde. Falls nötig wird der Bot den Pull-Request kommentieren - inklusive eines Links zum Akzeptieren der Vereinbarung. Die CLA für natürliche Personen ist zur Überprüfung als PDF-Datei verfügbar.

Bemerkung

Falls ein Beitrag einem Beschäftigungsverhältnis entstammt oder Eigentum des Arbeitgebers ist, ist es sehr wahrscheinlich, daß eine CLA für Unternehmen unterzeichnet werden muss, und per E-Mail an <qiskit@us.ibm.com> geschickt werden muss.

Pull-Requests¶

Wir verwenden GitHub Pull-Requests um Beiträge zu akzeptieren.

Obwohl nicht zwingend benötigt sollte ein Issue bzgl. dem Bug oder dem Feature an welchem man arbeitet vor dem Pull Request geöffnet werden. Dies ist ein wichtiger Schritt um die Diksussion mit der Community bzgl. der Änderungen zu beginnen. Mit einem Issue wird es ermöglicht die Idee zu besprechen und zu erörtern wie entsprechender Code implementiert werden muss. Des Weiteren kann so die Community erfahren an was man gerade arbeitet, ob Hilfe benötigt wird, und zusätzlich kann man auf das Issue in Diskussionen referenzieren.

Falls Code geschrieben wurde und man Hilfe benötigt diesen fertig zu stellen, man Feedback vor der Fertigstellung erwünscht, oder den Code vor der Implementierung diskutieren möchte, so kann man einen „Work In Progress“ Pull-Request eröffnen. Wenn man einen Pull-Request erstellt, muss dem Titel der Tag [WIP] (Work In Progress) vorangestellt werden. Dies gibt an, dass der Code im Pull-Request nicht final ist und sich ändern wird. Des Weiteren wird der entsprechende Commit nicht übernommen („merged“) bis die Änderung final ist. Der [WIP] Tag kann von einem selbst oder einem Reviewer entfernt werden, sobald der Code fertig ist und die Änderung übernommen werden kann („merged“).

Code-Review¶

Ein Code-Review ist öffentlich und kann von jedem ausgeführt werden. Nur „Maintainer“ haben Zugriff zu Merge-Commits, jedoch ist das Feedback der Community zu Pull-Requests sehr nützlich. Es hilft zusätzlich mehr über den Code zu lernen. Die Liste aller offenen Pull-Requests findet sich hier:

Element	Pull-Requests
qiskit-terra	https://github.com/Qiskit/qiskit-terra/pulls
qiskit-aer	https://github.com/Qiskit/qiskit-aer/pulls
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/pulls
Dokumente oder Qiskit Meta-Pakete	https://github.com/Qiskit/qiskit/pulls

Commit-Nachricht¶

Der Inhalt einer Commit-Nachricht beschreibt die Änderung und ist genauso wichtig wie die Änderung selbst. Die Commit-Nachricht liefert den Kontext nicht nur für den Code-Review, sondern auch für den Verlauf der Änderungen im Git-Log. Eine detaillierte Commit-Nachricht erleichtert den Code-Review und liefert den Kontext, falls jemand die Änderung in der Zukunft nachvollziehen möchte. Für eine Commit-Nachricht sollten folgende Dinge beachtet werden:

Man sollte nicht annehmen, dass der Reviewer versteht, was das ursprüngliche Problem war.

When reading an issue, after a number of back & forth comments, it is often clear what the root cause problem is. The commit message should have a clear statement as to what the original problem is. The bug is merely interesting for historical background on how the problem was identified. It should be possible to review a proposed patch for correctness from the commit message, without needing to read the bug ticket.

Gehen Sie nicht davon aus, dass der Code selbsterklärend/selbstdokumentierend ist.

Was für eine Person selbsterklärend ist, ist möglicherweise nicht verständlich für jemand anders. Man sollte immer dokumentieren, was das ursprüngliche Problem war und wie man es löst. Dies gilt für jede Änderung mit Ausnahme von offensichtlichen Tippfehlern.

Beschreiben Sie, warum eine Änderung vorgenommen wird.

Ein verbreiteter Fehler ist es nur zu dokumentieren wie ein Code geschrieben wurde, ohne zu erklären warum der Entwickler den Code so geschrieben hat. Natürlich sollte die Code-Struktur beschrieben werden; dies gilt insbesondere bei größeren Änderungen. Jedoch sollte man ebenso die Motivation für die Änderungen dokumentieren.

Lesen Sie die Commit-Nachricht, um zu sehen, ob sie Hinweise auf eine verbesserte Codestruktur liefert.

Bei grösseren Commit-Nachrichten wird es oft deutlich, dass ein Commit in mehrere Teile hätte aufgeteilt werden sollen. Man sollte nicht davor zurück schrecken die Änderung entsprechend anzupassen und in mehrere Pull-Requests zu splitten.

Bevor man ein Review durchführt sollte sichergestellt werden, dass genügend Informationen vorliegen.

Wenn GitHub eine Email bzgl. eines neuen Pull-Requests versendet, ist darin nur minimale Information enthalten - in der Regel die Commit-Nachricht und eine Liste der Dateien, die von einer Änderung betroffen sind. Aufgrund der hohen Patchanzahl, muss eine Commit-Nachricht ausreichend Informationen für potentielle Reviewer enthalten.

Die erste Commit-Zeile ist am wichtigsten.

In Git-Commits hat die erste Zeile der Commit-Nachricht eine besondere Bedeutung. Sie wird als Standardtitel für Pull-Request, Betreffzeile von E-Mail-Benachrichtigungen, Annotationsnachrichten in Git, gitk-Viewer-Anmerkungen, Merge-Commit-Nachrichten und an vielen weiteren Stellen verwendet, in denen es auf Platz ankommt. Neben der Zusammenfassung der Änderung selbst sollte es genau mitteilen, welche Teile des Codes betroffen sind.

Darüber hinaus wird die erste Zeile der Commit-Nachricht der Eintrag im generierten Changelog, sobald der PR im Changelog als hinzugefügt markiert ist. Es ist von entscheidender Bedeutung, dass Sie klare und prägnante zusammenfassende Zeilen verfassen.

Beschreiben Sie alle Einschränkungen des aktuellen Codes.

Wenn der Code, an dem man gearbeitet hat, noch Spielraum für künftige Verbesserungen lässt oder bestimmte Einschränkungen hat, sollte man das in seiner Commit-Nachricht vermerken. Dies zeigt dem Reviewer, dass das Problem umfassend betrachtet wurde und welche Kompromisse zugunsten kurzfristiger Zielen gegenüber langfristiger Absichten eingegangen wurden.

Referenzen zu Issues hinzufügen.

Wenn der Commit ein Issue löst, sollte man diesen Issue in der Commit-Nachricht referenzieren. Benutzen Sie diese Syntax:

Fixes #1234

falls es das Issue behebt (GitHub schließt das Issue automatisch, wenn der Pull-Request gemerged wird).

Grundsätzlich sollte man folgendes beherzigen:

Die Commit-Nachricht muss alle Informationen enthalten, welche benötigt werden um die Änderung komplett zu verstehen und auf Korrektheit prüfen zu können. Weniger ist nicht mehr.

Dokumentieren Sie Ihren Code¶

Bei Änderungen an einem Element sollte man stets die zugehörigen Docstrings und die Dokumentation unter docs/apidocs im Repository des jeweiligen Elements entsprechend aktualisieren. Um die Dokumentation eines Elements lokal zu generieren, führt man tox -edocs aus, um die Dokumentation zu kompilieren und die Ausgabe in docs/_build/html zu speichern. Dies führt auch der Docs-CI-Job auf Azure-Pipelines aus und stellt ein Zip-Archiv mit der Ausgabe zur Verfügung, welches man herunterladen und lokal ansehen kann.

Bei Fehlern, Wünschen oder Vorschlägen zur Gesamtdokumentation, welche im Qiskit/qiskit Repository verwaltet wird, öffnet man ein documentation issue.

Gute erste Beiträge¶

Wenn Sie einen Beitrag zu Qiskit leisten möchten, sich aber nicht sicher sind, womit Sie anfangen wollen, werden für Einsteiger geeignete Aufgaben durch die Kennzeichnung „good first issue“ hervorgehoben. Diese Aufgaben wurden durch Mitwirkende danach geprüft und gekennzeichnet, ob ein Einsteiger in der Lage sein sollte, sie zu lösen. Mit anderen Worten: Detaillierte Kenntnisse von Qiskit sind keine Voraussetzung, um einen Fix für solche Problem zu entwickeln.

Deprecation Policy¶

Qiskit-Benutzer müssen wissen, ob ein Feature oder eine API, auf die sie sich verlassen, auch morgen noch von der Software unterstützt werden. Das Wissen, unter welchen Bedingungen das Projekt ein Feature oder eine API entfernen (oder auf eine nicht rückwärtskompatible Art ändern) kann, ist für den Benutzer wichtig. Um die richtigen Erwartungen zu vermitteln, gilt folgende Richtlinie für die API- bzw. Feature-DepreKation/-Entfernung bei Qiskit:

1. Features, APIs, or configuration options are marked deprecated in the code. Appropriate DeprecationWarning class warnings will be sent to the user. The deprecated code will be frozen and receive only minimal maintenance (just so that it continues to work as-is).

2. A migration path will be documented for current users of the feature. This will be outlined in the both the release notes adding the deprecation, and the release notes removing the feature at the completion of the deprecation cycle. If feasible, the warning message will also include the migration path. A migration path might be „stop using that feature“, but in such cases it is necessary to first judge how widely used and/or important the feature is to users, in order to determine a reasonable obsolescence date.

2a. The migration path must have existed in a least a prior release before the new feature can be deprecated. For example, if you have a function foo() which is going to be replaced with bar() you can’t deprecate the foo() function in the same release that introduces bar(). The bar() function needs to be available in a release prior to the deprecation of foo(). This is necessary to enable downstream consumers of Qiskit that maintain their own libraries to write code that works with > 1 release at a time, which is important for the entire ecosystem. If you would like to indicate that a deprecation will be coming in a future release you can use the PendingDeprecationWarning warning to signal this. But, the deprecation period only begins after a DeprecationWarning is being emitted.

3. An obsolescence date for the feature will be set. The feature must remain intact and working (although with the proper warning being emitted) in all releases pushed until after that obsolescence date. At the very minimum, the feature (or API, or configuration option) should be marked as deprecated (and continue to be supported) for at least three months of linear time from the release date of the first release to include the deprecation warning. For example, if a feature were deprecated in the 0.9.0 release of Terra, which was released on August 22, 2019, then that feature should still appear in all releases until at least November 22, 2019.

Dieser Zeitraum ist jedoch nur ein Minimum. Für wichtige Features sollte es mindestens der doppelte Zeitraum sein. Außerdem können Deprecated-Features nach dem Stable-Branch-Prinzip nur bei Minor-Version-Releases entfernt werden; sie sind nicht zur Rückportierung geeignet.

3a. A deprecated feature can not be removed unless it is deprecated in more than one release even if the minimum deprecation period has elapsed. For example, if a feature is deprecated in 0.20.0 which is released on January 20, 2022 and the next minor version release 0.21.0 is released on June 16, 2022 the deprecated feature can’t be removed until the 0.22.0 release, even though 0.21.0 was more than three months after the 0.20.0 release. This is important because the point of the deprecation warnings are to inform users that a potentially breaking API change is coming and to give them a chance to adapt their code. However, many users skip versions (especially if there are a large numbers of changes in each release) and don’t upgrade to every release, so might miss the warning if it’s only present for a single minor version release.

Deprecation-Warnungen¶

Der korrekte Weg, Deprecation-Warnungen auszugeben, ist die warn Funktion des warnings module der Python-Standardbibliothek zu nutzen. Die Warnungs-Klasse sollte eine DeprecationWarning sein. Ein Beispiel dafür wäre:

import warnings

def foo(input):
    warnings.warn('The qiskit.foo() function is deprecated as of 0.9.0, and '
                  'will be removed no earlier than 3 months after that '
                  'release date. You should use the qiskit.bar() function '
                  'instead.', DeprecationWarning, stacklevel=2)

Erwähnenswert ist hierbei das stack_level kwarg im warn() Aufruf. Dieses Argument definiert, welches Level im Call-Stack als die Zeile verwendet wird, welche die Warnung ausgelöst hat. Normalerweise sollte stack_level auf 2 gesetzt sein, da dies die Zeile zeigt, welche den die Warnung auslösenden Kontext aufgerufen hat. Im obigen Beispiel wäre das der Aufrufer von foo(). Definiert man dies nicht, würde die Warnung anzeigen, dass die Zeile in der foo() Funktion die Warnung ausgelöst hat, was für Nutzer, die den Ursprung einer Deprecation Warnung suchen, nicht sinnvoll ist. Der Wert kann jedoch angepasst werden, je nachdem, von wo warn() aufgerufen wird. Wenn zum Beispiel die Warnung immer durch eine private Methode ausgelöst wird, die nur von einer einzigen Stelle aus aufgerufen wird, könnte stack_level=3 besser geeignet sein.

Stable-Branch-Policy¶

Der Stable-Branch soll eine sichere Quelle für Fixes weitreichenden Bugs und Sicherheitsproblemen sein, die seit einem Release auf dem Master behoben wurden. Bei der Überprüfung eines PR für den Stable-Branch müssen wir das Risiko eines bestimmten Patches mit dem Mehrwehrt rechtfertigen, den es Benutzern des Stable-Branch bieten wird. Nur eine begrenzte Klasse von Änderungen ist für die Aufnahme in den Stable-Branch geeignet. Ein großer, riskanter Patch für ein großes Problem könnte Sinn machen, ebenso wie ein trivialer Fix eines Code-Zweigs zur Behandlung von relativ selten eintretenden Fehlern. Bei einer Änderung muss eine Reihe von Faktoren abgewogen werden:

Das Risiko einer Regression: Selbst die kleinsten Veränderungen bergen ein gewisses Risiko, etwas kaputt zu machen, und wir wollen Regressionen auf dem stabilen Zweig auf jeden Fall 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.
Ob der Fix bereits auf Master gesetzt ist: Eine Änderung muss der Backport einer bereits mit dem Master zusammengeführten Änderung sein, es sei denn, die Änderung macht auf Master grundsätzlich keinen Sinn.

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.

Zur Dokumentation beitragen¶

Die Qiskit-Dokumentation gestaltet sich nach der `Docs-as-Code<https://www.writethedocs.org/guide/docs-as-code/>`__-Philosophie, primär wird sie aus Qiskit-Quelltextkommentaren im Stil einer API-Dokumentation generiert.

Die Dokumentation wird mit Sphinx aus dem Master-Branch von Qiskit/qiskit/docs generiert. Der Großteil der Dokumentation, unter API-Referenz, speist sich aus Quelltextkommentaren der in Wo sich die Qiskit-Bestandteile befinden aufgeführten Repositories.

Aufbau der Dokumentation¶

Die Dokumentation in Qiskit ist so aufgebaut, so viel wie möglich der eigentlichen Dokumentation über Docstrings abzubilden. Das macht das Ergänzen und Korrigieren der Dokumentation während der Entwicklung einfacher, da die Dokumentation nahe am betroffenen Code ist. Im Aufbau der Dokumentation von Terra gibt es drei Ebenen:

Die .rst Dateien in docs/apidocs

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:

Die einzige außerhalb liegende .rst-Datei ist qiskit.rst. Sie enthält das Inhaltsverzeichnis. Wenn man eine neue .rst-Datei für die Dokumentation eines neuen Moduls anlegt, muss diese dort unter toctree hinzugefügt werden.

Der Docstring auf Modul-Ebene

Dieser Docstring befindet sich auf der Modulebene für das Modul, welches in der Anweisung automodule in der rst-Datei angegeben ist. Wenn es sich bei dem angegebenen Modul um ein Verzeichnis/Namespace handelt, sollte der Docstring in der Datei __init__.py für dieses Verzeichnis angegeben werden. Dieser Docstring auf Modulebene enthält weitere Details zu dem Modul, das dokumentiert wird. Die normale Struktur zu dieses Docstrings ist eine Beschreibung aller Klassen und Funktionen der öffentlichen API, die in diesem Modul enthalten sind. Dies geschieht in der Regel mit der ` autosummary Direktive <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>` __ (oder ` autodoc Direktiven <http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>` __ direkt, falls das Modul einfach ist, wie zum Beispiel im Fall ` `qiskit.execute ` `). Die Autosummary-Direktive wird verwendet, um eine Liste mit verschiedenen Python-Elementen (Klassen, Funktionen, etc.) direkt automatisch zu dokumentieren, ohne die Autodoc-Anweisungen für die einzelnen Elemente manuell aufrufen zu müssen. Der Modulebene Docstring gibt einen Überblick über die Funktionalität, die das Modul bereitstellt. Dies geschieht normalerweise, indem die verschiedenen Komponenten der öffentlichen API in mehrere Unterabschnitte gruppiert werden.

Anhand des vorherigen Beispiels zum dagcircuit-Modul könnte der Inhalt des Modul-Docstrings in qiskit/dagcircuit/__init__.py etwa so aussehen:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================
.. currentmodule:: qiskit.dagcircuit
DAG Circuits
============
.. autosummary::
   :toctree: ../stubs/
   DAGCircuit
   DAGNode
Exceptions
==========
.. autosummary::
   :toctree: ../stubs/
   DAGCircuitError
"""

Bemerkung

Dies ist nur ein Beispiel und der tatsächliche Docstring des dagcircuit-Moduls kann abweichen.

Der eigentliche Docstring der Objekte, die im Modul-Docstring aufgeführt sind

Alle öffentlichen Schnittstellen sollten nach Möglichkeit mit Beispielen dokumentiert sein. Für Docstrings werden dabei Google-Python-Style Docstrings verwendet. Diese werden mit der Napoleon Sphinx-Erweiterung verarbeitet. Die Napoleon Dokumentation enthält gute Beispiele, wie Docstrings formatiert werden sollten.

Bemerkung

Jede Sphinx-Direktive und jede rst-Formatierung kann in Docstrings verwendet werden, soweit dies sinnvoll ist. Eine oft genutzte Erweiterung ist z. B. die jupyter-execute Direktive. Mit ihr kann man einen Code-Block in Jupyter ausführen und sowohl den Code als auch dessen Ausgabe anzeigen. Das ist gerade für Visualisierungen sehr hilfreich.

Integration der Dokumentation¶

The hosted documentation at https://qiskit.org/documentation/ covers the entire Qiskit project; Terra is just one component of that. As such, the documentation builds for the hosted version are built by the Qiskit meta-package repository https://github.com/Qiskit/qiskit. When commits are merged to that repo, the output of Sphinx builds are uploaded to the qiskit.org website. Those Sphinx builds are configured to pull in the documentation from the version of the Qiskit elements installed by the meta-package at that point. For example, if the meta-package version is currently 0.13.0, then that will copy the documentation from Terra’s 0.10.0 release. When the meta-package’s requirements are bumped, then it will start pulling documentation from the new version. 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).

Während des Build-Prozesses werden die Inhalte aus docs/apidocs/ aller Module rekursiv in eine Kopie von doc/apidocs/ im Meta-Paket-Repository kopiert, inklusive aller anderen Elemente. Das bedeutet, dass was direkt unter docs/apidocs eines Elements liegt, bei einem Release auch direkt unter https://qiskit.org/documentation/apidoc/ liegt.

Übersetzen der Dokumentation¶

Die Qiskit-Dokumentation wird übersetzt (lokalisiert) mittels Crowdin, einer Software- und Web-Lokalisierungsplatform, die es Unternehmen ermöglicht Übersetzungsprojekte zu koordinieren und mit Gemeinschaften für Übersetzungen zu kollaborieren. Crowdin ermöglicht es unserer Gemeinschaft von Übersetzern, ihre Leistung zu steigern, indem die Arbeit die in die Übersetzung eines Satzes investiert wurde, automatisch wieder verwendet wird, um andere, ähnliche Sätze zu übersetzen. Crowdin macht Übersetzungen auch widerstandsfähig gegen viele Arten von Änderungen am Originalmaterial, bspw. das Verschieben von Sätzen sogar zwischen Dateien.

Anfragen zur Qiskit-Übersetzung werden im Qiskit Translations <https://github.com/Qiskit/qiskit-translations> Repository bearbeitet. Um bei der Qiskit-Übersetzung zu helfen, ist wie folgt vorzugehen:

Füge den Namen (oder die ID) zu der Datei LOCALIZATION_CONTRIBUTORS hinzu.
Erstelle einen Pull-Request (PR), um Änderungen zu mergen. Achte darauf, der Vorlage für Pull-Anforderung zu folgen.
Bemerkung
- Jeder Mitwirkende muss seinen eigenen Pull-Request erstellen und die Mitwirkenden-Lizenzvereinbarung - Contributors License Agreement (CLA) - unterschreiben.
- Die Pull-Request Zusammenfassung sollte die Sprache beinhalten, an der man mitwirken möchte.
- Falls es ein offenes Issue für eine Sprachanfrage gibt, füge den Link zum Thema PR hinzu.
Sie werden aufgefordert, das Qiskit-Zahler License Agreement (CLA) zu unterzeichnen; bitte tun Sie das.
Drei Mitwirkende pro Sprache sind mindestens erforderlich, dass diese hinzugefügt wird und offizielle Unterstützung von den Administratoren des Projekts erhält.
Unter den Mitwirkenden muss ein Übersetzungsleiter identifiziert werden, der als Verbindung zu den Administratoren des localization projects dient. Dieser muss zu Yuri Kobayashi (yurik@jp.ibm.com) per E-Mail Kontakt aufnehmen.
Wählen Sie im Projekt „Qiskit-Docs <https://crowdin.com/project/qiskit-docs>` __ Crowdin“ die Sprache aus, zu der Sie einen Beitrag leisten möchten.

Bemerkung

Wie im Blogbeitrag Qiskit in my language is Qiskit beschrieben, möchte man sicherstellen, dass eine übersetzte Sprache genug Unterstützung aus der Community hat, um ein Team aus Übersetzern, Korrekturlesern und Übersetzungsleitern zusammenzustellen. Als potentieller Übersetzungsleiter einer Sprache, oder Freiwilliger für ein neues Übersetzungsteam, öffnet man dazu einen Github Issue <https://github.com/Qiskit/qiskit/issues>`__ um eine Diskussion mit dem Qiskit Team zu starten und Mitwirkende für das Übersetzungsprojekt zu gewinnen.
Nachdem Join angeklickt wurde kopiert man die Pull-Request-URL in das Nachrichtenfeld, in dem man gefragt wird, warum man dem Crowdin Projekt beitreten möchte.

Die Administratoren des Crowddin-Projekts werden Ihre Anfrage überprüfen und Ihnen so schnell wie möglich Zugriff ermöglichen.

Aus Quellcode kompilieren¶

Sie können eine lokale Kopie der Dokumentation aus Ihrem lokalen Klon des Qiskit/qiskit-Repository wie folgt erstellen:

Klonen Sie das Qiskit-Repository.

git clone https://github.com/Qiskit/qiskit.git

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit.
```
cd qiskit
```
Erstellen Sie die Dokumentation, indem Sie zu Ihrem lokalen Klon Qiskit/qiskit navigieren und den folgenden Befehl in einem Terminal-Fenster ausführen.
```
tox -edocs
```
Wenn Sie das Programm ‚tox <https://tox.readthedocs.io/en/latest/>` _ nicht bereits installiert haben, installieren Sie es, indem Sie Folgendes ausführen:
```
pip install tox
```

Wenn Sie Änderungen an den lokalen RST-Dateien vornehmen, können Sie Ihre HTML-Dateien aktualisieren, indem Sie in einem Terminal-Fenster nach /doc/ navigieren und die folgenden Schritte ausführen:

tox -edocs

Dies erzeugt eine formatierte HTML-Version des lokalen Dokumentations-Repository im Unterverzeichnis /docs/_build/html.

Installieren aus Quelltext¶

Die Elemente aus dem Quelltext zu installieren, ermöglicht es auf die aktuellste Version von Qiskit zuzugreifen anstatt der Version, welche im Python-Package-Index (PyPI) veröffentlicht ist. Damit hat man die Möglichkeit, sich effizienter die neueste Version von Qiskit zu betrachten und zu erweitern.

Wenn Elemente und Komponenten aus dem Quelltext installiert werden, ist es Voreinstellung, dass die development-Version (welche mit dem git-master-Branch übereinstimmt) benutzt wird, und nicht die stable-Version (welche die Quelltextbasis der veröffentlichten pip-Pakete enthält). Weil die development-Versionen eines Elements oder einer Komponente üblicherweise die neuesten Funktionen und Änderungen beinhalten, erfordern diese in der Regel die Verwendung der development-Versionen aller übrigen Objekte.

Bemerkung

Die Terra- und Aer-Pakete benötigen beide zum Kompilieren aus dem Quelltext einen Compiler bevor man diese installieren kann. Ignis, Aqua und das „IBM Quantum Provider“-Backend benötigen keinen Compiler.

Das Installieren von Elementen aus dem Quellcode erfordert die folgende Reihenfolge, um die Installation von Elementen mit niedrigerer Version als der gewünschten zu vermeiden, falls die pip Versionen älter als die Quellversionen ist:

qiskit-terra
qiskit-aer
qiskit-ignis
qiskit-ibmq-provider (wenn man auf einen IBM Quantum-Device oder einen Online-Simulator zugreifen will)

Um gleichzeitig mit mehreren Komponenten und Elementen zu arbeiten, verwenden Sie für jedes Element die folgenden Schritte.

Bemerkung

Aufgrund der Verwendung von Namespaces in Python muss darauf geachtet werden, wie Pakete installiert werden. Wenn Sie ein Element aus dem Quelltext installieren möchten, verwenden Sie nicht das qiskit-Meta-Paket. Folgen Sie diesem Handbuch und verwenden Sie eine separate virtuelle Umgebung für die Entwicklung. Wenn Sie vorhaben, eine vorhandene Installation mit Ihrer Entwicklung zu mischen, lesen Sie die Informationen unter https://github.com/pypa/sample-namespace-packages/blob/master/table.md für eine Liste der funktionierenden Kombinationen von Installationsmethoden.

Einrichten der virtuellen Entwicklungsumgebung¶

Virtual environments are used for Qiskit development to isolate the development environment from system-wide packages. This way, we avoid inadvertently becoming dependent on a particular system configuration. For developers, this also makes it easy to maintain multiple environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).

Python venv

All Python versions supported by Qiskit include built-in virtual environment module venv.

Start by creating a new virtual environment with venv. The resulting environment will use the same version of Python that created it and will not inherit installed system-wide packages by default. The specified folder will be created and is used to hold the environment’s installation. It can be placed anywhere. For more detail, see the official Python documentation, Creation of virtual environments.

python3 -m venv ~/.venvs/qiskit-dev

Activate the environment by invoking the appropriate activation script for your system, which can be found within the environment folder. For example, for bash/zsh:

source ~/.venvs/qiskit-dev/bin/activate

Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections can be located for your system.

pip install -U pip

Conda

For Conda users, a new environment can be created as follows.

conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv

Installieren von Terra aus dem Quelltext¶

Installing from source requires that you have the Rust compiler on your system. To install the Rust compiler the recommended path is to use rustup, which is a cross-platform Rust installer. To use rustup you can go to:

https://rustup.rs/

which will provide instructions for how to install rust on your platform. Besides rustup there are other installation methods available too.

Once the Rust compiler is installed, you are ready to install Qiskit Terra.

Klonen Sie das Terra-Repository.

git clone https://github.com/Qiskit/qiskit-terra.git

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit-terra.
```
cd qiskit-terra
```
Falls Tests oder Linting-Checks durchgeführt werden sollen, muss man zusätzlich die Entwicklungsabhängigkeiten installieren.
```
pip install -r requirements-dev.txt
```
Installieren Sie qiskit-terra.
```
pip install .
```

Möchte man eine Installation im editierbaren Modus vornehmen - in dem Code-Änderungen im Projekt keine Neuinstallation erfordern - kann man das wie folgt machen:

pip install -e .

Installing in editable mode will build the compiled extensions in debug mode without optimizations. This will affect the runtime performance of the compiled code. If you’d like to use editable mode and build the compiled code in release with optimizations enabled you can run:

python setup.py build_rust --release --inplace

after you run pip and that will rebuild the binary in release mode.

If you are working on Rust code in Qiskit you will need to rebuild the extension code every time you make a local change. pip install -e . will only build the Rust extension when it’s called, so any local changes you make to the Rust code after running pip will not be reflected in the installed package unless you rebuild the extension. You can leverage the above build_rust command to do this (with or without --release based on whether you want to build in debug mode or release mode).

You can then run the code examples after installing Terra. You can run an example script with the following command.

python examples/python/using_qiskit_terra_level_0.py

Installieren von Aer aus dem Quelltext¶

Klonen Sie das Aer-Repository.

git clone https://github.com/Qiskit/qiskit-aer

Installieren Sie die Abhängigkeiten.
```
pip install cmake scikit-build
```

Ab hier ist die Installation von Aer abhängig vom verwendeten Betriebssystem. Da Aer ein kompiliertes C++ Programm mit einer Python-Schnittstelle ist, gibt es Nicht-Python Abhängigkeiten, um Aer zu kompilieren, welche spezifisch für das verwendete Betriebssystem sind.

Linux

Compiler-Abhängigkeiten installieren.

Die Kompilation von Aer benötigt einen C++-Compiler und entsprechende Header-Dateien.

Wenn Sie Fedora oder eine gleichwertige Linux-Distribution verwenden, installieren Sie dies:
```
dnf install @development-tools
```
Für Ubuntu/Debian installieren Sie es per:
```
apt-get install build-essential
```
Installieren Sie die OpenBLAS-Header.

Wenn Sie Fedora oder eine gleichwertige Linux-Distribution verwenden, installieren Sie dies:
```
dnf install openblas-devel
```
Für Ubuntu/Debian installieren Sie es per:
```
apt-get install libopenblas-dev
```

macOS

Abhängigkeiten installieren.

Um den Clang Compiler auf macOS zu verwenden, müssen Sie eine zusätzliche Bibliothek installieren, die OpenMP unterstützt. Sie können brew verwenden, um diese und andere Abhängigkeiten zu installieren.
```
brew install libomp
```
Installieren Sie dann eine BLAS-Implementierung; OpenBLAS ist die Standardauswahl.
```
brew install openblas
```
Als nächstes installiert man die Xcode Command Line Tools.
```
xcode-select --install
```

Windows

In Windows benötigt man Anaconda3 oder Miniconda3 um alle Abhängigkeiten installieren zu können.

Compiler-Abhängigkeiten installieren.

conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime

Installieren Sie binäre und Build-Abhängigkeiten.

conda install --update-deps -c conda-forge -y openblas cmake

qiskit-aer direkt kompilieren und installieren

Hat man pip < 19.0.0 installiert und benötigt keine benutzerdefinierte Konfiguration, kann man folgenden Befehl verwenden:
```
cd qiskit-aer
pip install .
```
Damit kompiliert und installiert man Aer.

Alternativ, wenn man eine neuere Version von pip verwendet oder eine spezielle Konfiguration benötigt, kann man das Python-Wheel von Hand erstellen.
```
cd qiskit-aer
python ./setup.py bdist_wheel
```
Wenn Sie während der Wheel-Erstellung eine benutzerdefinierte Option setzen müssen, finden Sie Informationen dazu unter Benutzerdefinierte Wheel-Konfiguration.

Nachdem das Python-Wheel erstellt wurde, wird es im dist/ Verzeichnis des Aer Repositorys gespeichert. Die genaue Version hängt davon ab
```
cd dist
pip install qiskit_aer-*.whl
```
Der genaue Dateiname der ausgegebenen Wheel-Datei hängt von der aktuellen Version von Aer ab.

Benutzerdefinierte Wheel-Konfiguration¶

Das Aer-Build-System verwendet scikit-build für die Kompilierung, wenn man die Python-Schnittstelle verwendet. Es fungiert dabei als Schnittstelle zu setuptools, um CMake aufzurufen und die Binärdateien für das lokale System zu kompilieren.

Durch die Komplexität, die mit dem Kompilieren von Binärdateien einhergeht, kann es sein, dass man für einen bestimmten Teil des Prozesses benutzerdefinierte Optionen angeben muss. Dies kann man mit:

python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]]

wobei die Optionen in eckigen Klammern [] optional sind und skbuild_opts, cmake_opts, build_tool_opts durch benutzerdefinierte Konfigurationen ersetzt werden. Eine Liste für CMake Optionen findet man unter: https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. Beispielsweise kann man folgenden Befehl verwenden:

python setup.py bdist_wheel -- -- -j8

Dadurch wird das Flag -j8 an das Build-System durchgereicht (in diesem Fall Automake), wodurch diesem mitgeteilt wird, dass man mit 8 parallelen Prozessen kompilieren möchte.

Ein typischer Fall für diese Optionen ist, beispielsweise in Linux, eine spezifische Version des C++-Compilers anzugeben (meistens, wenn die Standardversion zu alt ist):

python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7

dies teilt CMake mit, den Befehl g++-7, statt dem standardmäßigen g++, bei der Kompilation von Aer zu verwenden.

Ein weiterer typischer Fall ist, in bestimmten Umgebungen einen Plattformnamen anzugeben und das statische Linken zu deaktivieren.

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \
-- -DSTATIC_LINKING=False -- -j8

Hierbei ist --plat-name ein Flag für setuptools, um den in den Paket-Metadaten zu verwendenden Plattform-Namen anzugeben. -DSTATIC_LINKING ist ein Flag für CMake, um das statische Linken zu deaktivieren und -j8 ist ein Flag für Automake, um 8 Prozesse bei der Kompilierung zu verwenden.

Eine Liste der gängigen Optionen je nach Plattform ist:

Plattform	Tool	Option	Use-Case
All	Automake	`-j`	Gefolgt von einer Zahl, legt die Anzahl der Prozesse fest, die für die Kompilierung verwendet werden sollen.
Linux	CMake	`-DCMAKE_CXX_COMPILER`	Wird verwendet, um einen bestimmten C++ -Compiler anzugeben. Dies ist häufig erforderlich, wenn der standardmäßig verwendete g++ zu alt ist.
OSX	setuptools	`--plat-name`	Wird verwendet, um den Plattformnamen im ausgegebenen Python-Paket anzugeben.
OSX	CMake	`-DSTATIC_LINKING`	Wird verwendet um anzugeben, ob statisch gelinkt werden soll oder nicht.

Bemerkung

Manche dieser Optionen sind nicht plattformspezifisch. Die entsprechenden Plattformen sind aufgeführt, weil sie meistens dort genutzt werden. In der jeweiligen Dokumentation des Tools findet man bei Bedarf weitere Informationen.

Installieren von Ignis aus dem Quelltext¶

Klonen Sie das Ignis-Repository.

git clone https://github.com/Qiskit/qiskit-ignis.git

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit-ignis.
```
cd qiskit-ignis
```
Wenn Sie Tests oder Linting-Prüfungen durchführen wollen, installieren Sie die Entwicklungsabhängigkeiten. Dies ist nicht erforderlich, um das qiskit-ignis-Paket zu installieren oder zu verwenden, wenn es aus dem Quellcode installiert wird.
```
pip install -r requirements-dev.txt
```
Installieren Sie Ignis.
```
pip install .
```

Falls Sie es im editierbaren Modus - in welchem Quelltextänderungen im Projekt keine Reinstallation erfordern - installieren möchten, können Sie das mit diesem Befehl tun:

pip install -e .

Installieren des IBM Quantum Provider aus dem Quelltext¶

Klonen Sie das Repository ‚qiskit-ibmq-provider‘.

git clone https://github.com/Qiskit/qiskit-ibmq-provider.git

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit-ibmq-provider.
```
cd qiskit-ibmq-provider
```
Wenn Sie Tests oder Linting-Checks durchführen wollen, installieren Sie die Entwicklungsabhängigkeiten. Dies ist nicht erforderlich, um das qiskit-ibmq-Provider-Paket zu installieren oder zu verwenden, falls es aus dem Quellcode installiert wird.
```
pip install -r requirements-dev.txt
```
Installieren Sie qiskit-ibmq-provider.
```
pip install .
```

Falls Sie es im editierbaren Modus - in welchem Quelltextänderungen im Projekt keine Reinstallation erfordern - installieren möchten, können Sie das mit diesem Befehl tun:

pip install -e .

Qiskit Versioning¶

The Qiskit project is made up of several elements each performing different functionality. Each is independently useful and can be used on their own, but for convenience we provide this repository and meta-package to provide a single entrypoint to install all the elements at once. This is to simplify the install process and provide a unified interface to end users. However, because each Qiskit element has its own releases and versions, some care is needed when dealing with versions between the different repositories. This document outlines the guidelines for dealing with versions and releases of both Qiskit elements and the meta-package.

For the rest of this guide the standard Semantic Versioning nomenclature will be used of: Major.Minor.Patch to refer to the different components of a version number. For example, if the version number was 0.7.1, then the major version is 0, the minor version 7, and the patch version 1.

Meta-package Version¶

The Qiskit meta-package version is an independent value that is determined by the releases of each of the elements being tracked. Each time we push a release to a tracked component (or add an element) the meta-package requirements, and version will need to be updated and a new release published. The timing should be coordinated with the release of elements to ensure that the meta-package releases track with element releases.

Adding New Tracked Elements¶

When a new Qiskit element is being added to the meta-package requirements, we need to increase the Minor version of the meta-package.

For example, if the meta-package is tracking 2 elements qiskit-aer and qiskit-terra and its version is 0.7.4. Then we release a new element qiskit-ignis that we intend to also have included in the meta-package. When we add the new element to the meta-package we increase the version to 0.8.0.

Patch Version Increases¶

When any Qiskit element that is being already tracked by the meta-package releases a patch version to fix bugs in a release, we need also bump the requirement in the setup.py and then increase the patch version of the meta-package.

For example, if the meta-package is tracking 3 elements qiskit-terra==0.8.1, qiskit-aer==0.2.1, and qiskit-ignis==0.1.4 with the current version 0.9.6. When qiskit-terra release a new patch version to fix a bug 0.8.2 the meta-package will also need to increase its patch version and release, becoming 0.9.7.

Additionally, there are occasionally packaging or other bugs in the meta-package itself that need to be fixed by pushing new releases. When those are encountered we should increase the patch version to differentiate it from the broken release. Do not delete the broken or any old releases from pypi in any situation, instead just increase the patch version and upload a new release.

Minor Version Increases¶

Besides when adding a new element to the meta-package, the minor version of the meta-package should also be increased anytime a minor version is increased in a tracked element.

For example, if the meta-package is tracking 2 elements qiskit-terra==0.7.0 and qiskit-aer==0.1.1 and the current version is 0.7.5. When the qiskit-aer element releases 0.2.0 then we need to increase the meta-package version to be 0.8.0 to correspond to the new release.

Major Version Increases¶

The major version is different from the other version number components. Unlike the other version number components, which are updated in lock step with each tracked element, the major version is only increased when all tracked versions are bumped (at least before 1.0.0). Right now, all the elements still have a major version number component of 0, and until each tracked element in the meta-repository is marked as stable by bumping the major version to be >=1, then the meta-package version should not increase the major version.

The behavior of the major version number component tracking after when all the elements are at >=1.0.0 has not been decided yet.

Optional Extras¶

In addition to the tracked elements, there are additional packages built on top of Qiskit which are developed in tandem with Qiskit, for example, the application repositories like qiskit-optimization. For convienence these packages are tracked by the Qiskit metapackage as optional extras that can be installed with Qiskit. Releases of these optional downstream projects do not trigger a metapackage release as they are unpinned and do not affect the metapackage version. If there is a compatibility issue between Qiskit and these downstream optional dependencies and the minimum version needs to be adjusted in a standalone release, this will only be done as a patch version release as it’s a packaging bugfix.

Qiskit Element Requirement Tracking¶

While not strictly related to the meta-package and Qiskit versioning, how we track the element versions in the meta-package’s requirements list is important. Each element listed in the setup.py should be pinned to a single version. This means that each version of Qiskit should only install a single version for each tracked element. For example, the requirements list at any given point should look something like:

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

This is to aid in debugging, but also make tracking the versions across multiple elements more transparent.