Versionsstrategie des Qiskit SDK

Qiskit-Versionsnummern folgen dem Semantic Versioning. Die Versionsnummer besteht aus drei Hauptkomponenten: der Major-, Minor- und Patch-Version. In der Versionsnummer X.Y.Z ist X die Major-Version, Y die Minor-Version und Z die Patch-Version.

Breaking-API-Änderungen sind Major-Version-Releases vorbehalten. Der Mindestzeitraum zwischen Major-Version-Releases beträgt ein Jahr. Minor-Versionen führen neue Funktionen und Bugfixes ein, ohne die API-Kompatibilität zu brechen, und werden regelmäßig (derzeit alle drei Monate) ausschließlich für die aktuelle Major-Version veröffentlicht. Patch-Versionen bieten Fixes für Bugs, die in der jeweils neuesten Minor-Version jeder aktiv unterstützten Release-Serie (also der Major-Version) gefunden wurden. Es werden höchstens zwei Release-Serien gleichzeitig unterstützt, was nur während des Überschneidungszeitraums nach einem neuen Major-Version-Release der Fall ist – dazu weiter unten mehr.

Release-Zeitplan

Unten findest du einen vorläufigen Release-Zeitplan:

Einen aktuellen Release-Zeitplan findest du in der Meilenstein-Liste des Qiskit-GitHub-Projekts, die immer den aktuellen Release-Plan enthält.

Mit der Veröffentlichung einer neuen Major-Version wird die vorherige Major-Version mindestens sechs Monate lang mit ausschließlich Bugfixes und ein Jahr lang mit Sicherheitsfixes unterstützt. In dieser Zeit werden nur Patch-Releases für diese Major-Version veröffentlicht. Eine abschließende Patch-Version wird veröffentlicht, wenn der Support eingestellt wird; dieses Release dokumentiert auch das Ende des Supports für diese Major-Version-Serie. Ein längeres Support-Fenster für die vorherige Major-Version ist notwendig, damit nachgelagerte Qiskit-Nutzer und ihre Anwender Zeit haben, ihren Code zu migrieren. Nachgelagerte Bibliotheken, die von Qiskit abhängen, sollten ihre minimal erforderliche Qiskit-Version nicht sofort nach Erscheinen einer neuen Major-Version auf diese anheben, da die Nutzer der Bibliothek Zeit benötigen, um zu den neuen API-Änderungen zu migrieren. Ein verlängertes Support-Fenster für die vorherige Qiskit-Major-Version gibt nachgelagerten Projekten Zeit, die Kompatibilität mit der nächsten Major-Version sicherzustellen. Nachgelagerte Projekte können gleichzeitig zwei Release-Serien unterstützen, um ihren Nutzern einen Migrationspfad zu bieten.

Für die Zwecke des Semantic Versioning gilt die öffentliche Qiskit-API als jedes dokumentierte Modul, jede Klasse, Funktion oder Methode, die nicht als privat gekennzeichnet ist (mit einem Unterstrich _ als Präfix). Es kann jedoch explizite Ausnahmen für bestimmte dokumentierte APIs geben. In solchen Fällen werden diese APIs klar als noch nicht stabile Schnittstellen dokumentiert, und bei jeder Verwendung dieser instabilen Schnittstellen wird aktiv eine für Nutzer sichtbare Warnung ausgegeben. Darüber hinaus gilt in einigen Situationen eine als privat gekennzeichnete Schnittstelle als Teil der öffentlichen API. Typischerweise tritt dies nur in zwei Fällen auf: entweder bei einer abstrakten Schnittstellendefinition, bei der Unterklassen eine private Methode als Teil der Implementierung der Schnittstelle überschreiben/implementieren sollen, oder bei Low-Level-Methoden für fortgeschrittene Nutzung, die stabile Schnittstellen haben, aber nicht als sicher gelten, da der Nutzer selbst die Klassen-/Sicherheitsinvarianten einhalten muss (das kanonische Beispiel hierfür ist die Methode QuantumCircuit._append).

Die unterstützten Python-Versionen, die minimal unterstützte Rust-Version (für den Build von Qiskit aus dem Quellcode) und alle Python-Paketabhängigkeiten (einschließlich der minimal unterstützten Versionen der Abhängigkeiten), die Qiskit verwendet, sind nicht Teil der Rückwärtskompatibilitätsgarantien und können sich bei jedem Release ändern. Nur Minor- oder Major-Version-Releases erhöhen die Mindestanforderungen für die Nutzung oder den Build von Qiskit (einschließlich des Hinzufügens neuer Abhängigkeiten), aber Patch-Fixes können die Unterstützung für neue Versionen von Python oder anderen Abhängigkeiten einschließen. Die Mindestversion einer Abhängigkeit wird in der Regel nur erhöht, wenn ältere Versionen der Abhängigkeit nicht mehr unterstützt werden oder wenn es nicht möglich ist, die Kompatibilität mit dem neuesten Release der Abhängigkeit und der älteren Version aufrechtzuerhalten.

Upgrade-Strategie

Wenn eine neue Major-Version veröffentlicht wird, ist der empfohlene Upgrade-Pfad, zunächst auf die neueste Minor-Version der vorherigen Major-Version zu aktualisieren. Kurz vor einer neuen Major-Version wird eine abschließende Minor-Version veröffentlicht. Dieses abschließende Minor-Version-Release X.Y+1.0.0 ist äquivalent zu X.Y.0, enthält jedoch Warnungen und Deprecations für alle API-Änderungen, die in der neuen Major-Version-Serie vorgenommen werden.

Unmittelbar vor dem Release 1.0.0 wird beispielsweise ein Release 0.46.0 veröffentlicht. Das Release 0.46.0 ist äquivalent zum Release 0.45.0, enthält jedoch zusätzliche Deprecation-Warnungen, die die API-Änderungen dokumentieren, die als Teil des Releases 1.0.0 vorgenommen wurden. Dieses Muster wird für alle zukünftigen Major-Version-Releases verwendet.

Qiskit-Nutzer sollten zunächst auf diese abschließende Minor-Version aktualisieren, um etwaige Deprecation-Warnungen zu sehen und ihre Qiskit-Nutzung anzupassen, bevor sie ein potenziell brechendes Release ausprobieren. Die vorherige Major-Version wird mindestens sechs Monate lang unterstützt, um ausreichend Zeit für das Upgrade zu geben. Eine typische Vorgehensweise hierfür ist, die Maximalversion anzupinnen, um die Verwendung der nächsten Major-Release-Serie zu vermeiden, bis du sicher bist, dass Kompatibilität besteht. Das Angeben von beispielsweise qiskit<2 in einer Requirements-Datei, wenn die aktuelle Qiskit-Major-Version 1 ist, stellt sicher, dass du eine Qiskit-Version verwendest, die keine brechenden API-Änderungen enthält.

Das Begrenzen der Version auf weniger als die nächste Major-Version stellt sicher, dass du Deprecation-Warnungen siehst, bevor ein Major-Version-Release erscheint. Ohne diese Begrenzung installiert pip standardmäßig die neueste verfügbare Version.

Das QPY-Serialisierungsformat ist abwärtskompatibel, sodass ein neues Qiskit-Release immer eine QPY-Datei laden kann, die mit einem früheren Qiskit-Release erstellt wurde. Das Format ist jedoch nicht vorwärtskompatibel, sodass es grundsätzlich nicht möglich ist, QPY-Dateien, die mit einer neueren Qiskit-Version erstellt wurden, mit einem älteren Release zu laden. Um die Nutzer-Migration über Major-Version-Releases hinweg zu erleichtern, unterstützt die Funktion qiskit.qpy.dump() immer mindestens eine überlappende Version zwischen dem X.0.0- und dem X-1.Y.0-Release (wobei Y die letzte Minor-Version dieser Serie ist). Der Parameter qiskit.qpy.dump(..., version=...) ermöglicht das Speichern von QPY-Formatdateien, die von beiden Major-Versionen aus dem neueren Release geladen werden können. Weitere Details findest du in RFC 0020.

Pre-Releases

Für jedes Minor- und Major-Version-Release veröffentlicht Qiskit Pre-Releases, die mit PEP440 kompatibel sind. Typischerweise handelt es sich dabei um Release-Kandidaten der Form X.Y.0rc1. Die rc-Releases haben eine finalisierte API-Oberfläche und dienen zum Testen eines geplanten Releases.

Beachte, dass bei der Veröffentlichung eines der PEP440-Pre-Release-Suffixe (wie a, b oder pre) nicht dieselben Garantien wie bei einem rc-Release gelten; es handelt sich dabei lediglich um eine Vorschau-Version. Die API kann sich zwischen diesen Pre-Releases und dem finalen Release mit dieser Versionsnummer ändern. So kann beispielsweise 1.0.0pre1 eine andere endgültige API haben als 1.0.0.

Post-Releases

Wenn es Probleme mit der Paketierung eines Releases gibt, kann ein Post-Release veröffentlicht werden, um diese zu beheben. Diese folgen der Form X.Y.Z.1, wobei die vierte Ganzzahl angibt, dass es sich um das erste Post-Release des X.Y.Z-Releases handelt. Das Release qiskit-terra (der frühere Paketname für Qiskit) 0.25.2 hatte beispielsweise ein Problem mit der Veröffentlichung des Sdist-Pakets, und ein Post-Release 0.25.2.1 wurde veröffentlicht, das dieses Problem behoben hat. Der Code war identisch, und 0.25.2.1 hat ausschließlich das Paketierungsproblem des Releases behoben.

Wie Mitwirkende Deprecations kennzeichnen können

Anweisungen zum Hinzufügen von Deprecations zum Quellcode findest du im Deprecation-Leitfaden im Qiskit-SDK-Repository.