Strategia wersjonowania Qiskit SDK

Numery wersji Qiskit są zgodne z konwencją Semantic Versioning. Numer wersji składa się z trzech głównych komponentów: wersji głównej (major), pomocniczej (minor) i poprawkowej (patch). Na przykład w numerze wersji X.Y.Z, X to wersja główna, Y to wersja pomocnicza, a Z to wersja poprawkowa.

Przełomowe zmiany API są zarezerwowane dla wydań głównych (major). Minimalny okres między wydaniami głównymi wynosi jeden rok. Wersje pomocnicze (minor) wprowadzają nowe funkcje i poprawki błędów bez naruszania zgodności API i są okresowo (obecnie co trzy miesiące) publikowane wyłącznie dla bieżącej wersji głównej. Wersje poprawkowe (patch) dostarczają poprawki błędów zidentyfikowanych w najnowszej wersji pomocniczej każdej aktywnie obsługiwanej serii wydań (tj. wersji głównej). Jednocześnie obsługujemy co najwyżej dwie serie wydań, co ma miejsce wyłącznie w okresie nakładania się następującym po wydaniu nowej wersji głównej – opisanym dokładniej poniżej.

Harmonogram wydań

Poniżej zamieszczono orientacyjny harmonogram wydań:

Aktualny harmonogram wydań znajdziesz w liście kamieni milowych projektu Qiskit na GitHubie, która zawsze odzwierciedla bieżący plan wydań.

Po opublikowaniu nowej wersji głównej poprzednia wersja główna jest obsługiwana przez co najmniej sześć miesięcy wyłącznie z poprawkami błędów oraz przez rok w zakresie poprawek bezpieczeństwa. W tym czasie dla tej wersji głównej publikowane są tylko wersje poprawkowe. Ostateczna wersja poprawkowa jest publikowana w momencie zakończenia wsparcia – to wydanie dokumentuje również koniec wsparcia dla danej serii głównej. Dłuższe okno wsparcia dla poprzedniej wersji głównej jest potrzebne, aby konsumenci Qiskit i ich użytkownicy mieli czas na migrację kodu. Biblioteki zależne od Qiskit nie powinny podnosić minimalnej wymaganej wersji Qiskit do nowej wersji głównej zaraz po jej wydaniu, ponieważ baza użytkowników biblioteki potrzebuje czasu na migrację do nowych zmian API. Wydłużone okno wsparcia dla poprzedniej głównej wersji Qiskit daje projektom zależnym czas na zapewnienie zgodności z następną wersją główną. Projekty zależne mogą obsługiwać jednocześnie dwie serie wydań, umożliwiając użytkownikom ścieżkę migracji.

Na potrzeby wersjonowania semantycznego publiczne API Qiskit obejmuje każdy udokumentowany moduł, klasę, funkcję lub metodę, która nie jest oznaczona jako prywatna (poprzedzona podkreśleniem _). Mogą jednak istnieć wyraźne wyjątki dla konkretnych udokumentowanych API. W takich przypadkach API będą wyraźnie udokumentowane jako niestanowiące jeszcze stabilnych interfejsów, a przy każdym użyciu tych niestabilnych interfejsów będzie aktywnie emitowane ostrzeżenie widoczne dla użytkownika. Ponadto w pewnych sytuacjach interfejs oznaczony jako prywatny jest uznawany za część publicznego API. Zwykle dotyczy to tylko dwóch przypadków: definicji abstrakcyjnego interfejsu , w której podklasy mają nadpisywać/implementować prywatną metodę jako część implementacji interfejsu, lub zaawansowanych metod niskopoziomowych o stabilnych interfejsach, które nie są jednak uważane za bezpieczne w użyciu, gdyż to na użytkowniku spoczywa obowiązek przestrzegania niezwykłości klasy/bezpieczeństwa (kanonicznym przykładem jest metoda QuantumCircuit._append).

Obsługiwane wersje Pythona, minimalna obsługiwana wersja Rusta (do budowania Qiskit ze źródeł) oraz zależności od pakietów Pythona (w tym minimalne obsługiwane wersje zależności) używane przez Qiskit nie są objęte gwarancjami wstecznej zgodności i mogą ulec zmianie w dowolnym wydaniu. Minimalne wymagania dotyczące używania lub budowania Qiskit (w tym dodawania nowych zależności) będą podnoszone tylko w wydaniach pomocniczych lub głównych, jednak poprawki mogą obejmować wsparcie dla nowych wersji Pythona lub innych zależności. Minimalna wersja zależności jest zazwyczaj podnoszona tylko wtedy, gdy starsze wersje zależności wychodzą z wsparcia lub gdy utrzymanie zgodności z najnowszym wydaniem zależności i starszą wersją jest niemożliwe.

Strategia aktualizacji

Gdy zostaje wydana nowa wersja główna, zalecana ścieżka aktualizacji polega na przejściu najpierw do najnowszej wersji pomocniczej na poprzedniej wersji głównej. Tuż przed nową wersją główną zostanie opublikowana ostateczna wersja pomocnicza. To ostateczne wydanie pomocnicze X.Y+1.0.0 jest równoważne X.Y.0, ale zawiera ostrzeżenia i informacje o przestarzałości dotyczące zmian API wprowadzonych w nowej serii głównej.

Na przykład bezpośrednio przed wydaniem 1.0.0 zostanie opublikowana wersja 0.46.0. Wydanie 0.46.0 będzie równoważne wydaniu 0.45.0, ale z dodatkowymi ostrzeżeniami o przestarzałości dokumentującymi zmiany API wprowadzone w wersji 1.0.0. Wzorzec ten będzie stosowany przy wszystkich przyszłych wydaniach głównych.

Użytkownicy Qiskit powinni najpierw zaktualizować się do tej ostatecznej wersji pomocniczej , aby zobaczyć wszelkie ostrzeżenia o przestarzałości i dostosować swoje użycie Qiskit przed próbą przejścia na potencjalnie przełomowe wydanie. Poprzednia wersja główna będzie obsługiwana przez co najmniej sześć miesięcy, aby zapewnić wystarczający czas na aktualizację. Typowym sposobem zarządzania tym procesem jest przypięcie wersji maksymalnej, aby uniknąć używania serii następnej wersji głównej do momentu potwierdzenia zgodności. Na przykład wpisanie qiskit<2 w pliku wymagań, gdy bieżąca główna wersja Qiskit to 1, gwarantuje używanie wersji Qiskit bez przełomowych zmian API.

Ograniczenie wersji do wartości mniejszej niż następna wersja główna zapewnia, że zobaczysz wszelkie ostrzeżenia o przestarzałości przed wydaniem głównym. Bez tego ograniczenia pip domyślnie instaluje najnowszą dostępną wersję.

Format serializacji QPY jest wstecznie zgodny, dzięki czemu nowe wydanie Qiskit zawsze może wczytać plik QPY wygenerowany przez wcześniejsze wydanie. Jednak format nie jest zgodny w przód, więc co do zasady nie jest możliwe wczytanie plików QPY wygenerowanych przez nowszą wersję Qiskit za pomocą starszego wydania. Aby ułatwić użytkownikom migrację między wydaniami głównymi, funkcja qiskit.qpy.dump() zawsze obsługuje co najmniej jedną nakładającą się wersję między wydaniem X.0.0 a X-1.Y.0 (gdzie Y to ostatnia wersja pomocnicza tej serii). Parametr qiskit.qpy.dump(..., version=...) umożliwia zapisywanie plików w formacie QPY, które mogą być wczytywane przez obie wersje główne z nowszego wydania. Więcej szczegółów znajdziesz w RFC 0020.

Wersje wstępne

Dla każdego wydania pomocniczego i głównego Qiskit publikuje wersje wstępne zgodne ze standardem PEP440. Zazwyczaj są to kandydaci do wydania w formie X.Y.0rc1. Wydania rc mają sfinalizowane API i służą do testowania planowanego wydania.

Należy pamiętać, że gdy publikowany jest jeden z sufiksów wersji wstępnej PEP440 (takich jak a, b lub pre), nie ma on takich samych gwarancji jak wydanie rc i jest jedynie wydaniem podglądowym. API może się zmienić między tymi wersjami wstępnymi a ostatecznym wydaniem z danym numerem wersji. Na przykład 1.0.0pre1 może mieć inne ostateczne API niż 1.0.0.

Wersje końcowe

Jeśli w opakowaniu wydania wystąpią problemy, może zostać opublikowana wersja końcowa (post-release) w celu ich naprawienia. Będą one miały formę X.Y.Z.1, gdzie czwarta liczba całkowita oznacza, że jest to pierwsze wydanie końcowe wydania X.Y.Z. Na przykład wydanie qiskit-terra (historyczna nazwa pakietu Qiskit) 0.25.2 miało pewien problem z publikacją pakietu sdist i zostało opublikowane wydanie końcowe 0.25.2.1 naprawiające ten problem. Kod był identyczny, a wersja 0.25.2.1 naprawiła jedynie problem z pakowaniem.

Jak współtwórcy mogą oznaczać przestarzałości

Zapoznaj się z przewodnikiem dotyczącym przestarzałości w repozytorium Qiskit SDK, aby dowiedzieć się, jak dodawać oznaczenia przestarzałości do kodu źródłowego.