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 im Sinne dieses Ziels anschliessen kann.

Wo sich die Qiskit-Bestandteile befinden¶

Der Code von Qiskit 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
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/issues
Dokumente oder Qiskit Meta-Package	https://github.com/Qiskit/qiskit/issues

Falls man eine Idee für ein neues Feature hat, sollte ein Enhancement-Issue im entsprechenden Issue-Tracker eröffnet werden. Wenn ein neues Issue eröffnet wird, dann wird eine Diskussion gestartet um zu erörtern in wiefern die Idee in das Projekt passt, wie sie implementiert werden kann, etc.

Code Beisteuern¶

Styleguide¶

Um einen konsistenten Code-Stil in dem Projekt sicherzustellen werden Pylint und pycodesytle verwendet um zu überprüfen ob Code-Beiträge konform sind und den Styleguide respektieren. Um zu überprüfen ob Änderungen mit dem Styleguide konform sind, den folgenden Befehl ausführen: 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 Fertigstellung 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¶

Eine 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
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/pulls
Dokumente oder Qiskit Meta-Package	https://github.com/Qiskit/qiskit/pulls

Commit-Nachrichten¶

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 jedoch auch für die Historie 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.

Wenn man ein Issue und eine Reihe von Kommentaren liest ist die Ursache des Problems in der Regel schnell klar. Die Commit-Nachricht sollte klarstellen was das ursprüngliche Problem ist. Im Falle eines Bugs ist es prinzipiell wichtig zu wissen wie das Problem festgestellt wurde. Es sollte mittels der Commit-Nachricht möglich sein einen Patch auf Korrektheit zu überprüfen ohne vorher das Bug Ticket zu lesen.

Man sollte nicht annehmen der Code sei selbsterklärend.

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

Man sollte beschreiben wieso eine Änderung vorgenommen wurde.

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.

Man sollte die Commit-Nachricht lesen um zu überprüfen ob sie eine verbesserte Code-Struktur beschreibt.

Bei grösseren Commit-Nachrichten wird es oft deutlich, dass ein Commit in mehrere Teile aufgeteilt werden sollte. 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 die wichtigste.

Die erste Zeile hat bei Git-Commits eine besondere Bedeutung. Sie wird als Standard Pull-Request Titel, Betreff der E-Mail-Benachrichtigung, Git-Annotate-Nachricht, Gitk-Viewer-Anmerkungen, Merge-Commit-Nachrichten und vielen weiteren Orten verwendet, wo begrenzter Platz für Nachrichten ist. Neben einer Zusammenfassung der Änderung, sollte in ihr auch stehen, welchen Teil des Codes die Änderung betrifft.

Zusätzlich wird die erste Zeile einer Commit Nachricht als Eintrag im automatisch generierten Changelog verwendet, wenn der Pull-Request gekennzeichnet wurde, dort aufgenommen zu werden. Daher ist es sehr wichtig, klare und prägnante Zusammenfassungen zu schreiben.

Einschränkungen des derzeitigen Codes beschreiben.

Wenn der Code, an dem man gearbeitet hat, noch Spielraum für künftige Verbesserung lässt oder bestimmte Einschränkungen oder Grenzen hat, sollte man dies in seiner Commit-Nachricht angeben. Dies zeigt dem Reviewer, dass das Problem in Gänze betrachtet wurde und welche Kompromisse zugunsten von kurzfristigen Zielen gegen langfristige Wünsche eingegangen wurden.

Referenzen zu Issues hinzufügen.

Wenn der Commit einen Issue löst, sollte man diesen Issue in der Commit-Nachricht referenzieren. Dies ist die Syntax:

Fixes #1234

um das Issue zu beheben (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.

Code-Dokumentation¶

Bei Änderungen an einem Element sollte man immer sichergehen, die zugehörigen Docstrings und die Dokumentation unter docs/apidocs im Repository des jeweiligen Elements entsprechend zu 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 zusammengeführten Dokumentation, welche im Qiskit/qiskit Repository verwaltet wird, öffnet man ein documentation issue.

Guter Einstieg¶

Das Issue-Label good first issue kennzeichnet Vorgänge, die ideal für Einsteiger sind, welche mitwirken möchten, sich aber nicht sicher sind, wo man anfangen soll. Dabei handelt es sich um Vorgänge, welche von Mitwirkenden als anfängerfreundlich eingestuft wurden. Eine tiefere Kenntnis von Qiskit ist dann meist keine Voraussetzung, um das Issue zu lösen.

Deprecation-Richtlinie¶

Qiskit-Nutzer müssen wissen, ob eine Funktion oder eine API, auf die sie sich verlassen, auch in Zukunft durch die Software unterstützt wird. Für den Anwender ist es wichtig zu wissen, unter welchen Bedingungen ein Feature oder eine API aus dem Projekt entfernt (oder in einer nicht abwärtskompatiblen Weise geändert) werden kann. Um Erwartungen zu steuern gelten bei Qiskit die Folgenden Richtlinien, nach denen die Entfernung von APIs und Features gehandhabt werden:

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.

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. Since releases do not occur at fixed time intervals, a deprecation warning may only occur in one release prior to removal.

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.

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 Argument 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 Kontext aufgerufen hat, der die Warnung ausgelöst 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 Stelle aus aufgerufen wird, könnte stack_level=3 besser geeignet sein.

Das Stable Branch Prinzip¶

Der Stable-Branch ist als sichere Quelle von kritischen Bugfixes und Sicherheitspatches gedacht, welche auf dem Master-Branch seit dem letzten Release veröffentlicht wurden. Bei der Prüfung eines Stable-Branch-Pull-Requests, muss man das Risiko eines jeden Patches gegen den Nutzen für die Benutzer des Stable-Branch abwägen. Nur einige bestimmte Arten von Änderungen sind geeignet, um in den Stable-Branch aufgenommen zu werden. Das könnte sowohl ein grosser, riskanter Patch für ein schwerwiegendes Problem, aber auch ein kleiner, trivialer Fix für einen unbedeutenden Fehlerfall sein. Eine Reihe an Faktoren müssen für eine Änderung berücksichtigt 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 Nutzen aus Benutzersicht: Reparieren wir etwas, das Nutzer auch tatsächlich wahrnehmen und falls ja, wie wichtig ist es?
Wie autark die Änderung ist: 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 die Änderung bereits im Master-Branch ist: Eine Änderung muss eine Rückportierung einer bereits im Master-Branch übernommenen Änderung sein, ausser natürlich die Änderung ist nicht sinnvoll im Master-Branch.

Rückportierungsprozess:¶

Bei der Rückportierung einer Änderung vom Master in den Stable-Branch, wollen wir eine Referenz zur Ä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össeren Commits (wie bspw. eines zusammengefassten Pull-Requests) rückportieren möchte vom Master, 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 dieser einzeln 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 sich daraus ergebenden Patch vorschlagen. Um die Prüfung des Stable-Branch zu vereinfachen, belässt man dabei die Conflicts Zeilen in der Commit-Nachricht.

Labels zur Rückportierung¶

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 Label entfernt werden.

Um zu zeigen, dass die Auswahl des Stable Branch als Ziel in einem Pull-Request kein Fehler war, verwendet man [Stable] im Titel. Zusätzlich gibt man eine Referenz zum Pull-Request der Änderung im Master Branch an, welche man rückportiert.

Zur Dokumentation beitragen¶

Die Qiskit-Dokumentation gestaltet sich nach der Dokumentation-wie-Quelltext-Philosophie, primär gespeist aus Qiskit-Quelltextkommentaren im Stil einer API-Dokumentation.

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 in den 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 betreffenden Code ist. Im Aufbau der Dokumentation von Terra gibt es drei Ebenen:

Die .rst Dateien in docs/apidocs

Diese Dateien werden verwendet, um Sphinx mitzuteilen, welche Module in die Dokumentation aufgenommen werden sollen. Dabei gibt es zwei Arten von Information: Eine Interne Referenz oder einen Querverweis zu dem Modul, welches die interne Verlinkung innerhalb der Dokumentation beschreibt und eine Auto-Modul Direktive um die Docstrings des Moduls aus dem spezifizierten Import-Pfad zu parsen. Als Beispiel ein Ausschnitt der Datei dagcircuit.rst:

.. _qiskit-dagcircuit:


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

Die einzige .rst Datei die außerhalb liegt, ist qiskit.rst. Diese 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

Dies ist der Docstring für das Modul, welches über die automodule Direktive in der rst-Datei angegeben wird. Wenn das angegebene Modul ein Verzeichnis oder ein Namespace ist, muss sich der Docstring in der Datei __init__.py dieses Verzeichnisses befinden. Der Docstring auf Modul-Ebene enthält weitere Details über das dokumentierte Modul. Der reguläre Aufbau beschreibt dabei alle Klassen und Funktionen der öffentlichen API des Moduls. Dies macht man üblicherweise mit der autosummary Direktive (oder direkt mit der autodoc Direktive, wenn das Modul einfach gehalten ist, wie bspw. bei qiskit.execute). Die autosummary Direktive wird verwendet, um eine gesammelte Liste verschiedener Python Objekte (Klassen, Funktionen, etc.) zu erstellen, ohne für jedes einzeln die autodoc Direktive aufrufen zu müssen. Im Docstring auf Modul-Ebene gibt man einen groben Überblick über die Funktionalität des Moduls, indem man die verschiedenen Komponenten der öffentlichen API in mehreren Unterkategorien zusammenfasst.

Anhand des vorherigen dagcircuit Modul Beispiels, 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 von diesem abweichen.

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

Alle öffentlichen Schnittstellen sollten bestmöglich und, wenn nötig, mit Beispielen dokumentiert sein. Für Docstrings werden dabei Google Python Style Docstrings verwendet. Diese werden mit der Napoleon Sphinx Erweiterung erfasst. Die Napoleon Dokumentation enthält gute Beispiele, wie Docstrings formatiert werden sollten.

Bemerkung

Jede Sphinx Direktive und jedes rst Format kann in Docstrings verwendet werden, soweit dies sinnvoll ist. Eine oft genutzte Erweiterung ist bspw. 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¶

Die Dokumentation unter https://qiskit.org/documentation/ deckt das komplette Qiskit Projekt ab; Terra ist davon nur eine Komponente. Daher wird die Dokumentation für die Webseite aus dem Qiskit Meta-Paket Repository https://github.com/Qiskit/qiskit erstellt. Wenn Commits in dieses Repository übernommen werden, wird das Ergebnis des Sphinx-Builds auf qiskit.org hochgeladen. Die Sphinx-Builds sind so konfiguriert, dass sie die Dokumentation der einzelnen Qiskit-Elemente mit der Version, welche im Meta-Paket angegeben ist verwenden. Wenn das Meta-Paket bspw. in Version 0.13.0 ist, wird die Dokumentation der 0.10.0 Version von Terra verwendet. Wenn die Versionsnummern in den Abhängigkeiten des Meta-Pakets aktualisiert werden, wird auch die Dokumentation der neuen Versionen übernommen. Das bedeutet, dass Korrekturen für eine fehlerhafte API Dokumentation ein neues Release benötigen. Korrekturen an der Dokumentation sind valide Rückportierungen für ein Stable Patch Release anhand der Stable Branch Regelung (siehe entsprechendes Kapitel).

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

Übersetzen der Dokumentation¶

Die Qiskit-Dokumentation wird übersetzt (lokalisiert) mit 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 Wirkung zu verstärken, 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 und das 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, an welcher man mitwirken möchte, beinhalten.
- Falls es ein offenes Issue für eine Sprachanfrage gibt, füge den Link zum Thema PR hinzu.
Man wird gebeten die Qiskit-Mitwirkendenlizenzvereinbarung - Contributors License Agreement (CLA) - zu unterzeichnen, was man dann bitte tun sollte.
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.
Im Crowdin-Projekt Qiskit-Docs wählt man nun die Sprache, an welcher man mitwirken möchte.

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 man auf Join geklickt hat, fügt man nun die URL zu seinem Pull-Request in das Nachrichtenfeld ein in dem man gefragt wird warum man dem Crowdin Projekt beitreten möchte.

Die Administratoren des Crowdin-Projekts werden das Beitrittsgesuch überprüfen und so schnell wie möglich Zugriff geben.

Aus Quelltext erzeugen¶

Mit diesen Schritten lässt sich aus einem geklonten Qiskit/qiskit Repository eine lokale Kopie der Dokumentation erzeugen:

Das Qiskit Repository klonen.

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

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit.
```
cd qiskit
```
Um die Dokumentation zu erstellen führt man auf der Kommandozeile den folgenden Befehl im Verzeichnis des lokalen Qiskit/qiskit Klons aus.
```
tox -edocs
```
Hat man den Befehl tox noch nicht installiert, muss man dies wie folgt nachholen:
```
pip install tox
```

Während man an den lokalen RST Dateien arbeitet, kann man die HTML Dateien aktualisieren, indem man in den Ordner /doc/ wechselt und diesen Befehl auf der Kommandozeile ausführt:

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 anzusehen 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 der ü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.

Um zu verhindern, ungewünschte frühere Versionen der Elemente zu installieren, wenn die Version von pip von der aktuellen abweicht, ist eine Installation in dieser Reihenfolge notwendig:

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

Um mit mehreren Komponenten und Elementen gleichzeitig zu arbeiten, müssen die folgenden Schritten für jedes Element ausgeführt werden.

Bemerkung

Aufgrund der Namensraum-Kapselung in Python, gilt es bei der Installation Sorgfalt walten zu lassen. Falls man ein Element aus dem Quelltext installieren möchte, darf man nicht das qiskit Meta-Paket verwenden. Am besten folgt man diesem Leitfaden und benutzt eine separate virtuelle Umgebung zum Entwickeln. Falls man eine existierende Installation mit seiner Entwicklungsumgebung kombinieren möchte, kann man auf https://github.com/pypa/sample-namespace-packages/blob/master/table.md nachsehen, welche Kombinationen von Installationsmethoden möglich sind.

Einrichten der virtuellen Entwicklungsumgebung¶

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

Installieren von Terra aus dem Quelltext¶

Eine Installation aus dem Quelltext erfordert einen C++-Compiler mit C++11-Unterstützung.

Compiler für Linux

Auf den meisten Linux-Plattformen ist der notwendige GCC-Compiler bereits installiert.

Compiler für macOS

Bei der Verwendung von macOS kann man den Clang-Compiler installieren, indem man XCode installiert. Zum Überprüfen, ob Xcode und Clang installiert sind, kann man folgenden Befehl in einem Terminal-Fenster ausführen.

clang --version

XCode und Clang installiert man mit folgendem Befehl.

xcode-select --install

Compiler für Windows

In Windows ist es am einfachsten den Visual C++-Compiler aus den Build Tools for Visual Studio 2017 zu installieren. Stattdessen kann man auch Visual Studio in der Version 2015 oder 2017 installieren. Dabei muss die Option den C++-Compiler zu installieren ausgewählt werden.

Sind die Compiler installiert, kann man mit der Installation von Qiskit Terra fortfahren.

Das Terra Repository klonen.

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

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit-terra.
```
cd qiskit-terra
```
Installieren der erforderlichen Python-Pakete aus dem qiskit-terra Verzeichnis.
```
pip install cython
```
Falls Tests oder Linting-Checks durchgeführt werden sollen, muss man zusätzlich die Entwicklungs-Abhängigkeiten installieren.
```
pip install -r requirements-dev.txt
```
qiskit-terra installieren.
```
pip install .
```

Möchte man eine Installation im editierbaren Modus vornehmen, das heisst, Code-Änderungen im Projekt benötigen keine Reinstallation, kann man das wie folgt machen:

pip install -e .

Nachdem Terra installiert ist, kann man mit dem folgenden Befehl die Code-Beispiele ausführen.

python examples/python/using_qiskit_terra_level_0.py

Bemerkung

Beabsichtigt man nicht, weitere Komponenten zu installieren, wird qiskit-terra eine RuntimeWarning mit dem Hinweis, dass qiskit-aer und qiskit-ibmq-provider nicht installiert sind, ausgeben. Dies ist beabsichtigt, da Benutzer normalerweise die weiteren Elemente verwenden wollen aber nicht realisieren, dass diese noch nicht installiert sind, oder, dass die Installation von Aer oder dem IBM Quantum Provider nicht funktioniert hat. Möchte man diese Warnung unterdrücken, fügt man dieses hinzu:

import warnings
warnings.filterwarnings('ignore', category=RuntimeWarning,
                        module='qiskit')

im Code vor jedem qiskit Import hinzu. Dies unterdrückt nur die Warnung der fehlenden Pakete qiskit-aer und qiskit-ibmq-provider. Andere Warnungen von qiskit oder sonstigen Paketen erscheinen weiterhin.

Installieren von Aer aus dem Quelltext¶

Das Aer Repository klonen.

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

Installationsvoraussetzungen installieren.
```
pip install cmake scikit-build cython
```

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 abhängig vom verwendeten Betriebssystem sind.

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
```
Benötigt man eine benutzerdefinierte Konfiguration während der Wheel-Erstellung, findet man Informationen unter Benutzerdefinierte Wheel-Konfiguration.

Nachdem das Python Wheel erstellt wurde, findet man es im dist/ Verzeichnis des Aer Repository. Die genaue Version hängt davon ab
```
cd dist
pip install qiskit_aer-*.whl
```
Der genaue Dateiname der Output 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. Bspw. kann man folgenden Befehl verwenden:

python setup.py bdist_wheel -- -- -j8

Dadurch wird die Option -j8 an das Build-System weitergereicht (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 Standard-Version zu alt ist):

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

dies teilt CMake mit, den g++-7 Befehl, statt dem standardmäßigen g++ zu verwenden, wenn es Aer kompiliert.

Ein weiterer typischer Fall ist, in bestimmten Umgebungen einen Plattform-Namen 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 eine Konfiguration für setuptools, um den in den Paket-Metadaten zu verwendenden Plattform-Namen anzugeben. -DSTATIC_LINKING ist eine Konfiguration für CMake, um das statische Linken zu deaktivieren und -j8 ist eine Konfiguration für Automake, um 8 Prozesse bei der Kompilierung zu verwenden.

Häufig genutzte Optionen aufgegliedert nach Plattform sind:

Plattform	Tool	Option	Anwendungsfall
Alle	Automake	-j	Gefolgt von einer Zahl, setzt diese Option die Anzahl der Prozesse, die zur Kompilierung verwendet werden soll.
Linux	CMake	-DCMAKE_CXX_COMPILER	Verwendet um einen spezifischen C++-Compiler festzulegen; oft erforderlich, wenn das voreingestellte g++ zu alt ist.
OSX	setuptools	–plat-name	Wird verwendet, um den Plattform-Namen im resultierenden Python-Paket zu setzen.
OSX	CMake	-DSTATIC_LINKING	Wird verwendet um anzugeben, ob statisch gelinkt werden soll oder nicht.

Bemerkung

Manche dieser Optionen sind nicht Plattform-spezifisch. Sie sind hier für die entsprechende Plattform 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¶

Das Ignis Repository klonen.

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

Klonen des Repository erzeugt einen lokalen Ordner namens qiskit-ignis.
```
cd qiskit-ignis
```
Falls Tests oder Linting-Checks durchgeführt werden sollen, muss man zusätzlich die Entwicklungs-Abhängigkeiten installieren. Dies ist nicht notwendig, um das qiskit-ignis Package zu installieren oder zu nutzen, wenn vom Quelltext installiert wird.
```
pip install -r requirements-dev.txt
```
Ignis installieren.
```
pip install .
```

Möchte man eine Installation im editierbaren Modus vornehmen, das heisst, Code-Änderungen im Projekt benötigen keine Reinstallation:

pip install -e .

Installieren von Aqua aus dem Quelltext¶

Das Aqua Repository klonen.

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

Klonen des Repository erzeugt ein lokales Verzeichnis namens qiskit-aqua.
```
cd qiskit-aqua
```
Falls Tests oder Linting-Checks durchgeführt werden sollen, muss man zusätzlich die Entwicklungs-Abhängigkeiten installieren. Dies ist nicht notwendig, um das qiskit-aqua Paket zu installieren oder zu nutzen, wenn vom Quelltext installiert wird.
```
pip install -r requirements-dev.txt
```
Aqua installieren.
```
pip install .
```

Möchte man eine Installation im editierbaren Modus vornehmen, das heisst, Code-Änderungen im Projekt benötigen keine Reinstallation:

pip install -e .

Installieren des IBM Quantum Provider aus dem Quelltext¶

Das qiskit-ibmq-provider Repository klonen.

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

Klonen des Repository erzeugt ein lokales Verzeichnis namens qiskit-ibmq-provider.
```
cd qiskit-ibmq-provider
```
Falls Tests oder Linting-Checks durchgeführt werden sollen, muss man zusätzlich die Entwicklungs-Abhängigkeiten installieren. Dies ist nicht notwendig, um das qiskit-ibmq-provider Paket zu installieren oder zu nutzen, wenn vom Quelltext installiert wird.
```
pip install -r requirements-dev.txt
```
qiskit-ibmq-provider installieren.
```
pip install .
```

Möchte man eine Installation im editierbaren Modus vornehmen, das heisst, Code-Änderungen im Projekt benötigen keine Reinstallation:

pip install -e .