Strategie verzování Qiskit SDK

Čísla verzí Qiskitu se řídí Sémantickým verzováním. Číslo verze se skládá ze tří hlavních složek: hlavní, vedlejší a záplatové verze. Například v čísle verze X.Y.Z je X hlavní verze, Y je vedlejší verze a Z je záplatová verze.

Zpětně nekompatibilní změny API jsou vyhrazeny pro vydání hlavních verzí. Minimální doba mezi vydáními hlavních verzí je jeden rok. Vedlejší verze přinášejí nové funkce a opravy chyb bez narušení kompatibility API a jsou pravidelně (v současnosti každé tři měsíce) vydávány pouze pro aktuální hlavní verzi. Záplatové verze poskytují opravy chyb identifikovaných v nejnovější vedlejší verzi každé aktivně podporované série vydání (tedy hlavní verze). Podporujeme nejvýše dvě série vydání najednou, což nastává pouze během období překryvu po vydání nové hlavní verze, podrobněji popsaného níže.

Harmonogram vydání

Orientační harmonogram vydání je uveden níže:

Aktuální harmonogram vydání najdeš v seznamu milníků projektu Qiskit na GitHubu, který vždy obsahuje aktuální plán vydání.

S vydáním nové hlavní verze je předchozí hlavní verze podporována po dobu nejméně šesti měsíců pouze s opravami chyb a jeden rok s opravami zabezpečení. Během této doby jsou pro tuto hlavní verzi vydávány pouze záplatové verze. Finální záplatová verze je vydána při ukončení podpory a toto vydání také dokumentuje konec podpory pro danou sérii hlavních verzí. Delší okno podpory je pro předchozí hlavní verzi potřeba, protože dává navazujícím uživatelům Qiskitu a jejich uživatelům čas na migraci kódu. Navazující knihovny, které závisí na Qiskitu, by neměly okamžitě po vydání nové hlavní verze zvyšovat svou minimální požadovanou verzi Qiskitu, protože uživatelé knihovny potřebují čas na migraci na nové změny API. Prodloužené okno podpory pro předchozí hlavní verzi Qiskitu dává navazujícím projektům čas zajistit kompatibilitu s následující hlavní verzí. Navazující projekty mohou najednou poskytovat podporu pro dvě série vydání, aby svým uživatelům umožnily migraci.

Pro účely sémantického verzování je veřejné API Qiskitu považováno za jakýkoliv zdokumentovaný modul, třídu, funkci nebo metodu, která není označena jako soukromá (předponou podtržítka _). Mohou však existovat explicitní výjimky pro konkrétní zdokumentovaná API. V takových případech budou tato API jasně zdokumentována jako rozhraní, která zatím nejsou považována za stabilní, a při každém použití těchto nestabilních rozhraní bude aktivně vydáváno uživatelsky viditelné varování. Navíc v některých situacích je rozhraní označené jako soukromé považováno za součást veřejného API. Typicky se to vyskytuje pouze ve dvou případech: buď jde o definici abstraktního rozhraní, kde podtřídy mají přepisovat/implementovat soukromou metodu jako součást definice implementace rozhraní, nebo jde o pokročilé nízkoúrovňové metody se stabilními rozhraními, které však nejsou považovány za bezpečné k použití, protože zodpovědnost za dodržování invariantů třídy/bezpečnosti nese sám uživatel (kanonickým příkladem je metoda QuantumCircuit._append).

Podporované verze Pythonu, minimální podporovaná verze Rustu (pro sestavení Qiskitu ze zdrojového kódu) a jakékoli závislosti na Python balíčcích (včetně minimálních podporovaných verzí závislostí) používané Qiskitem nejsou součástí záruk zpětné kompatibility a mohou se změnit při jakémkoli vydání. Pouze vedlejší nebo hlavní verze zvýší minimální požadavky pro použití nebo sestavení Qiskitu (včetně přidávání nových závislostí), ale záplatové opravy mohou zahrnovat podporu nových verzí Pythonu nebo jiných závislostí. Minimální verze závislosti se obvykle zvyšuje pouze tehdy, když starší verze závislosti přestanou být podporovány nebo když není možné udržet kompatibilitu s nejnovějším vydáním závislosti a starší verzí.

Strategie aktualizací

Při vydání nové hlavní verze je doporučená cesta aktualizace nejprve přejít na nejnovější vedlejší verzi předchozí hlavní verze. Krátce před vydáním nové hlavní verze bude vydána finální vedlejší verze. Toto finální vydání vedlejší verze X.Y+1.0.0 je ekvivalentní X.Y.0, ale obsahuje varování a upozornění na zastaralost pro jakékoli změny API, které jsou provedeny v nové sérii hlavních verzí.

Například těsně před vydáním 1.0.0 bude vydána verze 0.46.0. Vydání 0.46.0 bude ekvivalentní vydání 0.45.0, ale s dalšími varováními o zastaralosti, která dokumentují změny API provedené jako součást vydání 1.0.0. Tento vzor bude použit pro všechna budoucí vydání hlavních verzí.

Uživatelé Qiskitu by nejprve měli přejít na tuto finální vedlejší verzi, aby viděli všechna varování o zastaralosti a upravili své používání Qiskitu před pokusem o potenciálně zpětně nekompatibilní vydání. Předchozí hlavní verze bude podporována alespoň šest měsíců, aby bylo dostatek času na aktualizaci. Typický způsob, jak to řídit, je připnout maximální verzi, aby se zabránilo použití série nové hlavní verze, dokud si nejsi jistý kompatibilitou. Například zadáním qiskit<2 v souboru požadavků, když je aktuální hlavní verze Qiskitu 1, zajistíš, že používáš verzi Qiskitu bez zpětně nekompatibilních změn API.

Omezení verze na méně než další hlavní verzi zajišťuje, že uvidíš varování o zastaralosti před vydáním hlavní verze. Bez tohoto omezení nainstaluje pip ve výchozím nastavení nejnovější dostupnou verzi.

Formát serializace QPY je zpětně kompatibilní, takže nové vydání Qiskitu může vždy načíst soubor QPY vygenerovaný starším vydáním Qiskitu. Formát však není dopředně kompatibilní, takže v zásadě není možné načíst soubory QPY vygenerované novější verzí Qiskitu pomocí staršího vydání. Pro usnadnění migrace uživatelů mezi vydáními hlavních verzí bude funkce qiskit.qpy.dump() vždy podporovat alespoň jednu překrývající se verzi mezi vydáním X.0.0 a X-1.Y.0 (kde Y je poslední vedlejší verze dané série). Parametr qiskit.qpy.dump(..., version=...) umožní ukládání souborů ve formátu QPY, které lze načíst oběma hlavními verzemi z novějšího vydání. Více podrobností v RFC 0020.

Předvydání

Pro každé vydání vedlejší a hlavní verze Qiskit vydává předverze, které jsou kompatibilní s PEP440. Typicky jde o release candidates ve tvaru X.Y.0rc1. Vydání rc budou mít finalizovaný povrch API a slouží k testování připravovaného vydání.

Poznámka: když je vydán jeden z předpon předvydání dle PEP440 (jako a, b nebo pre), nemá stejné záruky jako vydání rc a jde pouze o náhledové vydání. API se může mezi těmito předvydáními a finálním vydáním s daným číslem verze změnit. Například 1.0.0pre1 může mít jiné finální API než 1.0.0.

Vydání po vydání

Pokud se vyskytnou problémy s balením vydání, může být vydáno vydání po vydání (post-release) k jejich nápravě. Tato budou mít tvar X.Y.Z.1, kde čtvrté celé číslo označuje, že jde o první post-release vydání X.Y.Z. Například vydání qiskit-terra (dřívější název balíčku pro Qiskit) 0.25.2 mělo problém s publikováním balíčku sdist a bylo vydáno post-release 0.25.2.1, které tento problém napravilo. Kód byl identický a 0.25.2.1 pouze opravilo problém s balením pro dané vydání.

Jak mohou přispěvatelé označovat zastaralosti

Pokyny, jak přidávat označení zastaralostí do zdrojového kódu, najdeš v průvodci zastaralostmi v repozitáři Qiskit SDK.