Estratehiya sa bersyon ng Qiskit SDK
Ang mga numero ng bersyon ng Qiskit ay sumusunod sa Semantic Versioning.
Ang numero ng bersyon ay binubuo ng tatlong pangunahing bahagi: ang major, minor, at
patch na bersyon. Halimbawa, sa numero ng bersyon na X.Y.Z, ang X ay ang major na bersyon,
ang Y ay ang minor na bersyon, at ang Z ay ang patch na bersyon.
Ang mga pagbabagong nakaka-apekto sa API ay nakalaan para sa mga major na release ng bersyon. Ang pinakamaikling panahon sa pagitan ng mga major na release ng bersyon ay isang taon. Ang mga minor na bersyon ay nagpapakilala ng mga bagong feature at bug fix nang hindi nasisira ang compatibility ng API, at pana-panahon (kasalukuyang bawat tatlong buwan) ay inilalathala para lamang sa kasalukuyang major na bersyon. Ang mga patch na bersyon ay nagbibigay ng mga ayos para sa mga bug na natukoy sa pinakabagong minor na bersyon ng bawat aktibong sinusuportahang release series (iyon ay, ang major na bersyon). Sumusuporta kami ng hanggang dalawang release series sa isang pagkakataon, na nangyayari lamang sa panahon ng overlap kasunod ng isang bagong major na release ng bersyon, na inilarawan nang mas detalyado sa ibaba.
Iskedyul ng release​
Ang isang tentative na iskedyul ng release ay kasama sa ibaba:
Para sa isang napapanahong iskedyul ng release, sumangguni sa listahan ng milestones ng GitHub project ng Qiskit, na palaging naglalaman ng kasalukuyang plano ng release.
Sa paglabas ng isang bagong major na bersyon, ang nakaraang major na bersyon ay sinusuportahan ng hindi bababa sa anim na buwan na may mga bug fix lamang, at isang taon para sa mga security fix. Sa panahong ito, ang mga patch release lamang ang inilalathala para sa major na bersyon na ito. Ang isang panghuling patch na bersyon ay inilalathala kapag tinanggal na ang suporta, at ang release na iyon ay nagdodokumento rin ng katapusan ng suporta para sa major na bersyon series na iyon. Kailangan ng mas mahabang window ng suporta para sa nakaraang major na bersyon dahil nagbibigay ito sa mga downstream consumer ng Qiskit at sa kanilang mga gumagamit ng pagkakataon na i-migrate ang kanilang code. Ang mga downstream na library na umaasa sa Qiskit ay hindi dapat agad itaas ang kanilang minimum na kinakailangang bersyon ng Qiskit sa isang bagong major na bersyon kaagad pagkatapos ng release nito dahil kailangan ng oras ng user base ng library upang mag-migrate sa mga bagong pagbabago sa API. Ang pagkakaroon ng extended na window ng suporta para sa nakaraang major na bersyon ng Qiskit ay nagbibigay sa mga downstream na proyekto ng oras upang masiguro ang compatibility sa susunod na major na bersyon. Ang mga downstream na proyekto ay maaaring magbigay ng suporta para sa dalawang release series nang sabay upang bigyan ang kanilang mga gumagamit ng landas ng migration.
Para sa mga layunin ng semantic versioning, ang pampublikong API ng Qiskit ay itinuturing na
anumang dokumentadong module, klase, function, o method na hindi minarkahan bilang private
(na may underscore na prefix na _). Gayunpaman, maaaring may mga tahasang pagbubukod para sa
mga partikular na dokumentadong API. Sa ganitong mga kaso, malinaw na idodokumento ang mga API na ito
bilang hindi pa itinuturing na mga stable na interface, at isang babala na nakikita ng gumagamit ay
aktibong ibibigay sa anumang paggamit ng mga hindi stable na interface na ito. Bukod pa rito, sa ilang
sitwasyon, ang isang interface na minarkahan bilang private ay itinuturing na bahagi ng pampublikong
API. Karaniwang nangyayari ito sa dalawang kaso lamang: alinman sa isang abstract na kahulugan ng interface
kung saan ang mga subclass ay inilaan upang i-override/ipatupad ang isang private na method
bilang bahagi ng pagbibigay ng implementasyon ng interface, o advanced na paggamit ng
mga low-level na method na may mga stable na interface ngunit hindi itinuturing na ligtas na gamitin,
dahil ang responsibilidad ay nasa gumagamit upang mapanatili ang mga class/safety invariant mismo
(ang canonical na halimbawa nito ay ang QuantumCircuit._append na method).
Ang mga sinusuportahang bersyon ng Python, ang minimum na sinusuportahang bersyon ng Rust (para sa pagbuo ng Qiskit mula sa source), at anumang mga dependency ng Python package (kasama ang minimum na sinusuportahang mga bersyon ng mga dependency) na ginagamit ng Qiskit ay hindi bahagi ng mga garantiya ng backwards compatibility at maaaring magbago sa anumang release. Ang minor o major na release ng bersyon lamang ang magtatataas ng mga minimum na kinakailangan para sa paggamit o pagbuo ng Qiskit (kasama ang pagdaragdag ng mga bagong dependency), ngunit ang mga patch fix ay maaaring magsama ng suporta para sa mga bagong bersyon ng Python o iba pang mga dependency. Karaniwang ang minimum na bersyon ng isang dependency ay tinatataas lamang kapag ang mga lumang bersyon ng dependency ay nag-expire na sa suporta o kapag hindi posible na mapanatili ang compatibility sa pinakabagong release ng dependency at ang mas lumang bersyon.
Estratehiya sa pag-upgrade​
Kapag may bagong major na bersyon na inilabas, ang inirerekomendang landas ng upgrade
ay ang una ay mag-upgrade sa pinakabagong minor na bersyon sa nakaraang major na
bersyon. Kaunti bago ang isang bagong major na bersyon, isang panghuling minor na bersyon ang
ilalathala. Ang panghuling minor na release ng bersyon na ito na X.Y+1.0.0 ay katumbas ng
X.Y.0 ngunit may mga babala at deprecation para sa anumang pagbabago sa API na
ginawa sa bagong major na bersyon series.
Halimbawa, kaagad bago ang 1.0.0 release, isang 0.46.0 release ang ilalathala. Ang 0.46.0 release ay katumbas ng 0.45.0 release ngunit may karagdagang mga babala ng deprecation na nagdodokumento ng mga pagbabago sa API na ginawa bilang bahagi ng 1.0.0 release. Ang pattern na ito ay gagamitin para sa anumang mga release ng major na bersyon sa hinaharap.
Ang mga gumagamit ng Qiskit ay dapat munang mag-upgrade sa panghuling minor na
bersyon na ito upang makita ang anumang mga babala ng deprecation at ayusin ang kanilang
paggamit ng Qiskit bago subukan ang isang posibleng breaking release. Ang nakaraang
major na bersyon ay susuportahan ng hindi bababa sa anim na buwan upang magbigay ng sapat na oras
para mag-upgrade. Ang isang tipikal na pattern upang pamahalaan ito ay i-pin ang maximum na bersyon upang
maiwasan ang paggamit ng susunod na major na release series hanggang sigurado ka sa compatibility.
Halimbawa, ang pagtukoy ng qiskit<2 sa isang requirements file kapag ang kasalukuyang
major na bersyon ng Qiskit ay 1 ay tinitiyak na gumagamit ka ng isang bersyon ng Qiskit
na walang mga breaking na pagbabago sa API.
Ang pag-cap ng bersyon na mas mababa sa susunod na major na bersyon
ay tinitiyak na makikita mo ang anumang mga babala ng deprecation bago ang isang
major na release ng bersyon.
Kung wala ang cap, ang pip ay nag-iinstall
ng pinakabagong bersyon na available bilang default.
Ang QPY serialization format ay backwards-compatible upang ang isang bagong Qiskit release ay palaging makaload ng isang QPY
file na na-generate gamit ang isang mas lumang release ng Qiskit. Gayunpaman, ang format ay hindi forward-compatible kaya, sa prinsipyo, hindi posible
na mag-load ng mga QPY file na na-generate gamit ang isang mas bagong bersyon ng Qiskit gamit ang isang mas lumang release. Upang mapadali ang migration ng gumagamit sa mga major na release ng bersyon, ang qiskit.qpy.dump() function ay palaging susuporta ng hindi bababa sa isang overlapping na bersyon sa pagitan ng X.0.0 at ng X-1.Y.0 release (kung saan ang Y ay ang huling minor na bersyon ng
series na iyon). Ang parameter na qiskit.qpy.dump(..., version=...) ay magbibigay-daan sa pag-save ng mga QPY format file na maaaring i-load ng parehong major na bersyon mula sa mas bagong
release. Tingnan ang karagdagang detalye sa RFC 0020.
Mga pre-release​
Para sa bawat minor at major na release ng bersyon, naglalathala ang Qiskit ng mga pre-release na
compatible sa PEP440. Karaniwang
ang mga ito ay mga release candidate ng form na X.Y.0rc1. Ang mga rc release
ay magkakaroon ng finalized na API surface at ginagamit upang subukan ang isang prospective na release.
Tandaan na kapag ang isa sa mga PEP440 pre-release suffix (tulad ng a, b, o pre) ay
inilathala, wala itong parehong mga garantiya ng isang rc release, at
preview release lamang ito. Ang API ay maaaring magbago sa pagitan ng mga pre-release na ito
at ng panghuling release na may numero ng bersyon na iyon. Halimbawa, ang 1.0.0pre1 ay maaaring may
ibang panghuling API kaysa sa 1.0.0.
Mga post-release​
Kung may mga isyu sa packaging ng isang release, isang post-release ay maaaring
ilabas upang ayusin ito. Ang mga ito ay sumusunod sa form na X.Y.Z.1 kung saan ang ikaapat na
integer ay nagpapahiwatig na ito ang unang post-release ng X.Y.Z release.
Halimbawa, ang qiskit-terra (ang legacy na pangalan ng package para sa Qiskit) 0.25.2
release ay may ilang isyu sa pag-publish ng sdist package, at isang post-release na
0.25.2.1 ay inilathala na nag-ayos ng isyung ito. Magkapareho ang code, at
ang 0.25.2.1 ay nag-ayos lamang ng isyu sa packaging para sa release.
Paano maaaring markahan ng mga contributor ang mga deprecation​
Sumangguni sa deprecation guide sa repository ng Qiskit SDK para sa mga instruksyon kung paano magdagdag ng mga deprecation sa source code.