Strategi versi Qiskit SDK
Nomor versi Qiskit mengikuti Semantic Versioning.
Nomor versi terdiri dari tiga komponen utama: versi major, minor, dan
patch. Misalnya, pada nomor versi X.Y.Z, X adalah versi major,
Y adalah versi minor, dan Z adalah versi patch.
Perubahan API yang breaking hanya dilakukan pada rilis versi major. Periode minimum antara rilis versi major adalah satu tahun. Versi minor memperkenalkan fitur baru dan perbaikan bug tanpa merusak kompatibilitas API, dan diterbitkan secara berkala (saat ini setiap tiga bulan) hanya untuk versi major saat ini. Versi patch memberikan perbaikan untuk bug yang ditemukan di versi minor terbaru dari setiap seri rilis yang aktif didukung (yaitu, versi major). Kita mendukung maksimal dua seri rilis sekaligus, yang hanya terjadi selama periode tumpang tindih setelah rilis versi major baru, dijelaskan lebih detail di bawah ini.
Jadwal rilis
Jadwal rilis sementara disertakan di bawah ini:
Untuk jadwal rilis terkini, lihat daftar milestones proyek GitHub Qiskit, yang selalu berisi rencana rilis saat ini.
Dengan rilis versi major baru, versi major sebelumnya didukung setidaknya enam bulan dengan hanya perbaikan bug, dan satu tahun untuk perbaikan keamanan. Selama waktu ini hanya rilis patch yang diterbitkan untuk versi major tersebut. Sebuah versi patch final diterbitkan saat dukungan dihentikan, dan rilis tersebut juga mendokumentasikan akhir dukungan untuk seri versi major itu. Jendela dukungan yang lebih lama diperlukan untuk versi major sebelumnya karena ini memberi kesempatan kepada pengguna downstream Qiskit dan penggunanya untuk memigrasikan kode mereka. Library downstream yang bergantung pada Qiskit tidak boleh langsung menaikkan versi minimum Qiskit yang dibutuhkan ke versi major baru segera setelah rilisnya karena basis pengguna library membutuhkan waktu untuk migrasi ke perubahan API baru. Dengan adanya jendela dukungan yang diperpanjang untuk versi major Qiskit sebelumnya, proyek downstream memiliki waktu untuk memastikan kompatibilitas dengan versi major berikutnya. Proyek downstream dapat memberikan dukungan untuk dua seri rilis sekaligus untuk memberi pengguna mereka jalur migrasi.
Untuk keperluan semantic versioning, API publik Qiskit dianggap sebagai
modul, kelas, fungsi, atau metode yang terdokumentasi yang tidak ditandai sebagai private
(dengan awalan underscore _). Namun, ada pengecualian eksplisit yang bisa dibuat untuk
API tertentu yang terdokumentasi. Dalam kasus seperti itu, API ini akan didokumentasikan dengan jelas
sebagai antarmuka yang belum stabil, dan peringatan yang terlihat oleh pengguna akan
aktif dikeluarkan pada setiap penggunaan antarmuka yang tidak stabil ini. Selain itu, dalam beberapa
situasi, antarmuka yang ditandai sebagai private dianggap sebagai bagian dari API publik.
Biasanya ini hanya terjadi dalam dua kasus: definisi antarmuka abstrak
di mana subkelas dimaksudkan untuk mengganti/mengimplementasikan metode private
sebagai bagian dari mendefinisikan implementasi antarmuka, atau metode tingkat rendah
untuk penggunaan lanjutan yang memiliki antarmuka stabil tetapi tidak dianggap aman untuk digunakan,
karena pengguna bertanggung jawab untuk menjaga invarian kelas/keamanan sendiri
(contoh kanoniknya adalah metode QuantumCircuit._append).
Versi Python yang didukung, versi Rust minimum yang didukung (untuk membangun Qiskit dari sumber), dan dependensi paket Python apa pun (termasuk versi minimum dependensi yang didukung) yang digunakan oleh Qiskit bukan merupakan bagian dari jaminan kompatibilitas mundur dan mungkin berubah selama rilis apa pun. Hanya rilis minor atau major yang akan menaikkan persyaratan minimum untuk menggunakan atau membangun Qiskit (termasuk menambahkan dependensi baru), tetapi perbaikan patch mungkin menyertakan dukungan untuk versi Python atau dependensi baru lainnya. Biasanya versi minimum sebuah dependensi hanya dinaikkan saat versi dependensi yang lebih lama tidak lagi didukung atau saat tidak mungkin untuk mempertahankan kompatibilitas dengan rilis terbaru dari dependensi tersebut dan versi lamanya.
Strategi upgrade
Saat versi major baru dirilis, jalur upgrade yang direkomendasikan
adalah dengan terlebih dahulu upgrade ke versi minor terbaru pada versi major
sebelumnya. Tidak lama sebelum versi major baru, sebuah versi minor final akan
diterbitkan. Rilis versi minor final X.Y+1.0.0 ini setara dengan
X.Y.0 tetapi dengan peringatan dan deprecation untuk perubahan API apa pun yang
dilakukan pada seri versi major baru.
Misalnya, tepat sebelum rilis 1.0.0, rilis 0.46.0 akan diterbitkan. Rilis 0.46.0 akan setara dengan rilis 0.45.0 tetapi dengan peringatan deprecation tambahan yang mendokumentasikan perubahan API yang dilakukan sebagai bagian dari rilis 1.0.0. Pola ini akan digunakan untuk rilis versi major di masa mendatang.
Pengguna Qiskit sebaiknya terlebih dahulu upgrade ke versi minor final ini
untuk melihat peringatan deprecation apa pun dan menyesuaikan penggunaan Qiskit mereka
sebelum mencoba rilis yang berpotensi breaking. Versi major sebelumnya
akan didukung setidaknya enam bulan untuk memberikan waktu yang cukup
untuk upgrade. Pola umum untuk mengelola ini adalah dengan mematok versi maksimum agar
tidak menggunakan seri rilis major berikutnya sampai kamu yakin kompatibilitasnya.
Misalnya, menentukan qiskit<2 dalam file requirements saat versi major Qiskit saat ini
adalah 1 memastikan kamu menggunakan versi Qiskit
yang tidak memiliki perubahan API yang breaking.
Membatasi versi di bawah versi major berikutnya
memastikan kamu melihat peringatan deprecation sebelum
rilis versi major.
Tanpa batasan tersebut, pip menginstal
versi terbaru yang tersedia secara default.
Format serialisasi QPY bersifat backwards-compatible sehingga rilis Qiskit baru selalu dapat memuat file QPY
yang dibuat dengan rilis Qiskit sebelumnya. Namun, format ini tidak forward-compatible sehingga, pada prinsipnya, tidak mungkin
memuat file QPY yang dibuat dengan versi Qiskit yang lebih baru menggunakan rilis yang lebih lama. Untuk memudahkan migrasi pengguna di antara rilis versi major, fungsi qiskit.qpy.dump() akan selalu mendukung setidaknya satu versi yang tumpang tindih antara rilis X.0.0 dan rilis X-1.Y.0 (di mana Y adalah versi minor terakhir dari
seri tersebut). Parameter qiskit.qpy.dump(..., version=...) memungkinkan penyimpanan file format QPY yang dapat dimuat oleh kedua versi major dari rilis yang lebih baru.
Lihat lebih detail di RFC 0020.
Pre-release
Untuk setiap rilis versi minor dan major, Qiskit menerbitkan pre-release yang
kompatibel dengan PEP440. Biasanya
ini adalah release candidate dengan bentuk X.Y.0rc1. Rilis rc
akan memiliki permukaan API yang sudah final dan digunakan untuk menguji rilis yang akan datang.
Perlu diperhatikan bahwa ketika salah satu sufiks pre-release PEP440 (seperti a, b, atau pre)
diterbitkan, tidak memiliki jaminan yang sama seperti rilis rc, dan hanya
merupakan rilis preview. API mungkin berubah antara pre-release ini
dan rilis final dengan nomor versi tersebut. Misalnya, 1.0.0pre1 mungkin memiliki
API final yang berbeda dari 1.0.0.
Post-release
Jika ada masalah dengan kemasan sebuah rilis, post-release mungkin
diterbitkan untuk memperbaikinya. Ini akan mengikuti bentuk X.Y.Z.1 di mana bilangan bulat keempat menunjukkan bahwa ini adalah post-release pertama dari rilis X.Y.Z.
Misalnya, rilis qiskit-terra (nama paket lama untuk Qiskit) 0.25.2
mengalami masalah dengan penerbitan paket sdist, dan post-release
0.25.2.1 diterbitkan yang memperbaiki masalah ini. Kodenya identik, dan
0.25.2.1 hanya memperbaiki masalah kemasan untuk rilis tersebut.
Cara kontributor menandai deprecation
Lihat panduan deprecation di repositori Qiskit SDK untuk petunjuk cara menambahkan deprecation ke kode sumber.