Strategia de versionare a Qiskit SDK

Numerele de versiune Qiskit urmează Semantic Versioning. Numărul de versiune este alcătuit din trei componente principale: versiunea majoră, versiunea minoră și versiunea de patch. De exemplu, în numărul de versiune X.Y.Z, X este versiunea majoră, Y este versiunea minoră, și Z este versiunea de patch.

Modificările care rup compatibilitatea API sunt rezervate lansărilor de versiuni majore. Perioada minimă dintre lansările de versiuni majore este de un an. Versiunile minore introduc funcționalități noi și remedieri de erori fără a rupe compatibilitatea API, și sunt publicate periodic (în prezent la fiecare trei luni) exclusiv pentru versiunea majoră curentă. Versiunile de patch furnizează remedieri pentru erorile identificate în cea mai recentă versiune minoră a fiecărei serii de lansări susținute activ (adică, versiunea majoră). Susținem cel mult două serii de lansări simultan, lucru care apare numai în perioada de suprapunere ce urmează după lansarea unei noi versiuni majore, descrisă mai detaliat mai jos.

Programul de lansări

Mai jos este inclus un program de lansări orientativ:

Pentru un program de lansări actualizat, consultă lista de milestone-uri a proiectului Qiskit de pe GitHub, care va conține întotdeauna planul curent de lansări.

Odată cu lansarea unei noi versiuni majore, versiunea majoră anterioară este susținută cel puțin șase luni doar cu remedieri de erori și un an pentru remedieri de securitate. În această perioadă, pentru această versiune majoră sunt publicate numai lansări de patch. O versiune finală de patch este publicată când suportul este încheiat, iar acea lansare documentează și sfârșitul suportului pentru seria respectivă de versiuni majore. O fereastră de suport mai extinsă este necesară pentru versiunea majoră anterioară, deoarece le oferă consumatorilor Qiskit din aval și utilizatorilor lor timp să își migreze codul. Bibliotecile din aval care depind de Qiskit nu ar trebui să ridice versiunea minimă Qiskit necesară la o nouă versiune majoră imediat după lansarea acesteia, deoarece baza de utilizatori a bibliotecii are nevoie de timp să migreze la noile modificări ale API. Existența unei ferestre extinse de suport pentru versiunea majoră anterioară Qiskit le oferă proiectelor din aval timp să asigure compatibilitatea cu versiunea majoră următoare. Proiectele din aval pot oferi suport pentru două serii de lansări simultan pentru a le oferi utilizatorilor lor o cale de migrare.

În sensul versionării semantice, API-ul public Qiskit este considerat orice modul, clasă, funcție sau metodă documentată care nu este marcată ca privată (cu prefix de subliniere _). Totuși, pot exista excepții explicite pentru anumite API-uri documentate. În astfel de cazuri, aceste API-uri vor fi clar documentate ca nefiind încă considerate interfețe stabile, și va fi emis activ un avertisment vizibil utilizatorului la orice utilizare a acestor interfețe instabile. În plus, în unele situații, o interfață marcată ca privată este considerată parte a API-ului public. De obicei, acest lucru apare numai în două cazuri: fie o definiție de interfață abstractă unde subclasele sunt destinate să suprascrie/implementeze o metodă privată ca parte a definirii unei implementări a interfeței, fie metode avansate de nivel scăzut care au interfețe stabile, dar nu sunt considerate sigure pentru utilizare, deoarece utilizatorul este cel responsabil să mențină el însuși invarianții de clasă/siguranță (exemplul canonic este metoda QuantumCircuit._append).

Versiunile Python suportate, versiunea minimă Rust suportată (pentru compilarea Qiskit din sursă) și orice dependențe de pachete Python (inclusiv versiunile minime suportate ale dependențelor) utilizate de Qiskit nu fac parte din garanțiile de compatibilitate inversă și se pot schimba în orice lansare. Numai lansările de versiuni minore sau majore vor ridica cerințele minime pentru utilizarea sau compilarea Qiskit (inclusiv adăugarea de noi dependențe), dar patch-urile pot include suport pentru versiuni noi ale Python sau ale altor dependențe. De obicei, versiunea minimă a unei dependențe este crescută numai când versiunile mai vechi ale dependenței ies din suport sau când nu este posibil să se mențină compatibilitatea cu cea mai recentă lansare a dependenței și versiunea mai veche.

Strategia de actualizare

Când este lansată o nouă versiune majoră, calea de actualizare recomandată este să actualizezi mai întâi la cea mai recentă versiune minoră a versiunii majore anterioare. Imediat înainte de o nouă versiune majoră, va fi publicată o versiune minoră finală. Această lansare finală de versiune minoră X.Y+1.0.0 este echivalentă cu X.Y.0, dar cu avertismente și deprecieri pentru orice modificări ale API care sunt realizate în seria noii versiuni majore.

De exemplu, imediat înainte de lansarea 1.0.0, va fi publicată o lansare 0.46.0. Lansarea 0.46.0 va fi echivalentă cu lansarea 0.45.0, dar cu avertismente de depreciere suplimentare care documentează modificările API realizate ca parte a lansării 1.0.0. Acest tipar va fi utilizat pentru orice viitoare lansări de versiuni majore.

Utilizatorii Qiskit ar trebui să actualizeze mai întâi la această versiune minoră finală pentru a vedea eventualele avertismente de depreciere și să-și ajusteze utilizarea Qiskit înainte de a încerca o lansare potențial incompatibilă. Versiunea majoră anterioară va fi susținută cel puțin șase luni pentru a oferi timp suficient de actualizare. Un tipar tipic pentru gestionarea acestui proces este să fixezi versiunea maximă pentru a evita utilizarea seriei de lansări majore următoare până când ești sigur de compatibilitate. De exemplu, specificând qiskit<2 într-un fișier de cerințe când versiunea majoră curentă Qiskit este 1, te asiguri că utilizezi o versiune Qiskit care nu are modificări API care rup compatibilitatea.

Limitarea versiunii sub versiunea majoră următoare garantează că vei vedea eventualele avertismente de depreciere înainte de o lansare majoră. Fără această limitare, pip instalează implicit cea mai nouă versiune disponibilă.

Formatul de serializare QPY este compatibil invers, astfel încât o nouă lansare Qiskit poate întotdeauna încărca un fișier QPY generat cu o lansare anterioară Qiskit. Totuși, formatul nu este compatibil direct, deci, în principiu, nu este posibil să încarci fișiere QPY generate cu o versiune mai nouă Qiskit folosind o lansare mai veche. Pentru a facilita migrarea utilizatorilor între lansările de versiuni majore, funcția qiskit.qpy.dump() va suporta întotdeauna cel puțin o versiune suprapusă între lansarea X.0.0 și lansarea X-1.Y.0 (unde Y este ultima versiune minoră a acelei serii). Parametrul qiskit.qpy.dump(..., version=...) va permite salvarea fișierelor în format QPY care pot fi încărcate de ambele versiuni majore din lansarea mai nouă. Vezi mai multe detalii în RFC 0020.

Pre-lansări

Pentru fiecare lansare de versiune minoră și majoră, Qiskit publică pre-lansări care sunt compatibile cu PEP440. De obicei, acestea sunt candidați de lansare de forma X.Y.0rc1. Lansările rc vor avea o suprafață API finalizată și sunt utilizate pentru a testa o lansare prospectivă.

Rețineți că atunci când sunt publicate unul dintre sufixele de pre-lansare PEP440 (precum a, b sau pre), acesta nu are aceleași garanții ca o lansare rc și este doar o lansare de previzualizare. API-ul se poate schimba între aceste pre-lansări și lansarea finală cu acel număr de versiune. De exemplu, 1.0.0pre1 poate avea un API final diferit față de 1.0.0.

Post-lansări

Dacă există probleme cu ambalarea unei lansări, poate fi emisă o post-lansare pentru a corecta acest lucru. Acestea vor urma forma X.Y.Z.1, unde al patrulea număr întreg indică că este prima post-lansare a lansării X.Y.Z. De exemplu, lansarea qiskit-terra (numele de pachet moștenit pentru Qiskit) 0.25.2 a avut o problemă cu publicarea pachetului sdist, iar o post-lansare 0.25.2.1 a fost publicată pentru a corecta această problemă. Codul era identic, iar 0.25.2.1 a remediat numai problema de ambalare pentru acea lansare.

Cum pot contribuitorii să marcheze deprecierile

Consultă ghidul de depreciere din repository-ul Qiskit SDK pentru instrucțiuni despre cum să adaugi deprecieri în codul sursă.