Стратегія версі онування Qiskit SDK
Номери версій Qiskit відповідають Семантичному версіонуванню.
Номер версії складається з трьох основних компонентів: мажорної, мінорної та
патч-версії. Наприклад, у номері версії X.Y.Z, X — це мажорна версія,
Y — мінорна версія, а Z — патч-версія.
Зміни, що порушують зворотну сумісність API, зарезервовані для мажорних випусків. Мінімальний період між мажорними випусками становить один рік. Мінорні версії вводять нові функції та виправлення помилок без порушення сумісності API і публікуються periodically (зараз кожні три місяці) лише для поточної мажорної версії. Патч-версії надають виправлення помилок, виявлених у найновішій мінорній версії кожної активно підтримуваної серії випусків (тобто мажорної версії). Ми підтримуємо не більше двох серій випусків одночасно, що відбувається лише протягом перехідного періоду після виходу нової мажорної версії, як описано детальніше нижче.
Графік випусків
Орієнтовний графік випусків наведено нижче:
Для отримання актуального графіку випусків звертайся до списку milestone проєкту Qiskit на GitHub, де завжди міститься поточний план випусків.
З виходом нової мажорної версії попередня мажорна версія підтримується щонайменше шість місяців лише з виправленнями помилок, і один рік — з виправленнями безпеки. Протягом цього часу для цієї мажорної версії публікуються лише патч-випуски. Фінальний патч-випуск публікується після закінчення підтримки, і цей випуск також документує завершення підтримки цієї серії мажорної версії. Тривале вікно підтримки попередньої мажорної версії необхідне для того, щоб надати споживачам Qiskit та їхнім користувачам час для міграції коду. Бібліотеки-залежності, що використовують Qiskit, не повинні підвищувати мінімальну необхідну версію Qiskit до нової мажорної версії одразу після її виходу, оскільки базі користувачів бібліотеки потрібен час для переходу до нових змін API. Наявність розширеного вікна підтримки попередньої мажорної версії Qiskit дає проєктам-залежностям час для забезпечення сумісності з наступною мажорною версією. Залежні проєкти можуть підтримувати дві серії випусків одночасно, щоб надати своїм користувачам шлях міграції.
Для цілей семантичного версіонування публічний API Qiskit вважається
будь-яким задокументованим модулем, класом, функцією або методом, що не позначений як приватний
(з префіксом підкреслення _). Однак можуть бути явні винятки для
конкретних задокументованих API. У таких випадках ці API будуть чітко задокументовані
як ті, що ще не вважаються стабільними інтерфейсами, і при будь-якому використанні цих нестабільних інтерфейсів буде активно видаватись попередження, видиме користувачу. Крім того, в деяких
ситуаціях інтерфейс, позначений як приватний, вважається частиною публічного
API. Зазвичай це відбувається лише у двох випадках: або це абстрактне визначення
інтерфейсу, де підкласи мають перевизначати/реалізовувати приватний метод
як частину реалізації інтерфейсу, або це методи низького рівня для розширеного
використання, що мають стабільні інтерфейси, але не вважаються безпечними для використання,
оскільки відповідальність за підтримку інваріантів класу/безпеки покладається на користувача
(канонічний приклад — метод QuantumCircuit._append).
Підтримувані версії Python, мінімальна підтримувана версія Rust (для збірки Qiskit з вихідного коду) та будь-які залежності Python-пакетів (включно з мінімальними підтримуваними версіями залежностей), що використовуються Qiskit, не є частиною гарантій зворотної сумісності та можуть змінюватися в будь-якому випуску. Лише мінорні або мажорні випуски підвищуватимуть мінімальні вимоги для використання або збірки Qiskit (включно з додаванням нових залежностей), але патч-виправлення можуть містити підтримку нових версій Python або інших залежностей. Зазвичай мінімальна версія залежності підвищується лише тоді, коли старіші версії залежності виходять з підтримки або коли неможливо підтримувати сумісність з останнім випуском залежності та старішою версією.
Стратегія оновлення
Коли виходить нова мажорна версія, рекомендований шлях оновлення
полягає в тому, щоб спочатку оновитися до найновішої мінорної версії попередньої мажорної
версії. Незадовго до нової мажорної версії буде опубліковано
фінальну мінорну версію. Цей фінальний мінорний випуск X.Y+1.0.0 еквівалентний
X.Y.0, але з попередженнями та позначками застарілого функціоналу для будь-яких змін API, що
вносяться в нову серію мажорної версії.
Наприклад, безпосередньо перед випуском 1.0.0 буде опубліковано випуск 0.46.0. Випуск 0.46.0 буде еквівалентний випуску 0.45.0, але з додатковими попередженнями про застарілий функціонал, що документують зміни API, зроблені як частину випуску 1.0.0. Цей шаблон використовуватиметься для будь-яких майбутніх мажорних випусків.
Користувачам Qiskit слід спочатку оновитися до цієї фінальної мінорної
версії, щоб побачити попередження про застарілий функціонал і підкоригувати своє використання
Qiskit перед переходом до потенційно зламного випуску. Попередня
мажорна версія підтримуватиметься щонайменше шість місяців, щоб дати достатньо часу
для оновлення. Типова практика управління цим — обмежувати максимальну версію, щоб
уникнути використання наступної серії мажорної версії, доки ти не впевнений у сумісності.
Наприклад, вказівка qiskit<2 у файлі requirements, коли поточна
мажорна версія Qiskit — 1, гарантує, що ти використовуєш версію Qiskit
без зламних змін API.
Обмеження версії нижче наступної мажорної версії
гарантує, що ти побачиш попередження про застарілий функціонал до
виходу мажорного випуску.
Без обмеження pip встановлює
найновішу доступну версію за замовчуванням.
Формат серіалізації QPY зворотно сумісний, тому новий випуск Qiskit завжди може завантажити файл QPY,
згенерований більш раннім випуском Qiskit. Однак формат не є прямо сумісним, тому, в принципі, неможливо
завантажити файли QPY, згенеровані більш новою версією Qiskit, використовуючи старіший випуск. Для полегшення міграції користувачів між мажорними випусками функція qiskit.qpy.dump() завжди підтримуватиме щонайменше одну перекриваючу версію між випусками X.0.0 та X-1.Y.0 (де Y — остання мінорна версія
тієї серії). Параметр qiskit.qpy.dump(..., version=...) дозволить зберігати файли формату QPY, що можуть завантажуватися обома мажорними версіями з більш нового
випуску. Детальніше дивись в RFC 0020.
Попередні випуски
Для кожного мінорного та мажорного випуску Qiskit публікує попередні випуски, що
сумісні з PEP440. Зазвичай
це кандидати на випуск у формі X.Y.0rc1. Випуски rc
матимуть фіналізовану поверхню API і використовуються для тестування майбутнього випуску.
Зверни увагу, що коли публікуються один із суфіксів попереднього випуску PEP440 (наприклад, a, b або pre),
він не має тих самих гарантій, що й випуск rc, і є
лише попереднім переглядом. API може змінюватися між цими попередніми випусками
та фінальним випуском з цим номером версії. Наприклад, 1.0.0pre1 може мати
інший фінальний API, ніж 1.0.0.
Пост-випуски
Якщо виникають проблеми з пакуванням випуску, може бути
виданий пост-випуск для їх виправлення. Вони матимуть форму X.Y.Z.1, де четверте
ціле число вказує, що це перший пост-випуск випуску X.Y.Z.
Наприклад, випуск qiskit-terra (застарілий пакет для Qiskit) 0.25.2
мав певну проблему з публікацією sdist-пакету, і був опублікований пост-випуск
0.25.2.1, що виправив цю проблему. Код був ідентичний, і
0.25.2.1 лише виправив проблему з пакуванням для цього випуску.
Як контрибютори можуть позначати застарілий функціонал
Звернись до посібника з позначення застарілого функціоналу у репозиторії Qiskit SDK для отримання інструкцій щодо додавання позначок застарілого функціоналу до вихідного коду.