Strategia di versioning dell'SDK Qiskit

I numeri di versione di Qiskit seguono il Versionamento Semantico. Il numero di versione è composto da tre componenti principali: la versione major, la versione minor e la versione patch. Ad esempio, nel numero di versione X.Y.Z, X è la versione major, Y è la versione minor e Z è la versione patch.

Le modifiche dell'API che introducono incompatibilità sono riservate alle release delle versioni major. Il periodo minimo tra release di versioni major è di un anno. Le versioni minor introducono nuove funzionalità e correzioni di bug senza rompere la compatibilità dell'API, e vengono pubblicate periodicamente (attualmente ogni tre mesi) soltanto per la versione major corrente. Le versioni patch forniscono correzioni per i bug identificati nella versione minor più recente di ciascuna serie di release attivamente supportata (ossia la versione major). Supportiamo al massimo due serie di release contemporaneamente, il che si verifica soltanto durante il periodo di sovrapposizione successivo al rilascio di una nuova versione major, descritto in maggiore dettaglio di seguito.

Calendario delle release

Di seguito è incluso un calendario di release indicativo:

Per un calendario di release aggiornato, consulta l'elenco delle milestone del progetto GitHub di Qiskit, che conterrà sempre il piano di release corrente.

Con il rilascio di una nuova versione major, la versione major precedente è supportata per almeno sei mesi con sole correzioni di bug, e per un anno per le correzioni di sicurezza. Durante questo periodo vengono pubblicate soltanto release patch per questa versione major. Una versione patch finale viene pubblicata al termine del supporto, e tale release documenta anche la fine del supporto per quella serie di versioni major. È necessaria una finestra di supporto più lunga per la versione major precedente, poiché questo dà ai consumatori downstream di Qiskit e ai loro utenti la possibilità di migrare il proprio codice. Le librerie downstream che dipendono da Qiskit non dovrebbero alzare la versione minima richiesta di Qiskit a una nuova versione major immediatamente dopo il suo rilascio, perché la base utenti della libreria ha bisogno di tempo per migrare alle nuove modifiche dell'API. Disporre di una finestra di supporto estesa per la versione major precedente di Qiskit dà ai progetti downstream il tempo di garantire la compatibilità con la versione major successiva. I progetti downstream possono fornire supporto per due serie di release contemporaneamente, per offrire ai propri utenti un percorso di migrazione.

Ai fini del versionamento semantico, la API pubblica di Qiskit comprende qualsiasi modulo, classe, funzione o metodo documentato che non sia contrassegnato come privato (con un prefisso underscore _). Tuttavia, possono essere previste eccezioni esplicite per specifiche API documentate. In tali casi, queste API saranno chiaramente documentate come interfacce non ancora considerate stabili, e un avviso visibile all'utente verrà emesso attivamente a ogni utilizzo di queste interfacce instabili. Inoltre, in alcune situazioni, un'interfaccia contrassegnata come privata è considerata parte della API pubblica. Tipicamente ciò si verifica soltanto in due casi: o una definizione di interfaccia astratta in cui le sottoclassi sono destinate a sovrascrivere/implementare un metodo privato come parte della definizione di un'implementazione dell'interfaccia, o metodi di basso livello ad uso avanzato che hanno interfacce stabili ma non sono considerati sicuri da usare, poiché è onere dell'utente rispettare gli invarianti di classe/sicurezza (l'esempio canonico è il metodo QuantumCircuit._append).

Le versioni di Python supportate, la versione minima di Rust supportata (per compilare Qiskit dal sorgente) e qualsiasi dipendenza da pacchetti Python (incluse le versioni minime supportate delle dipendenze) utilizzate da Qiskit non fanno parte delle garanzie di compatibilità con le versioni precedenti e possono cambiare durante qualsiasi release. Soltanto le release di versioni minor o major alzeranno i requisiti minimi per l'utilizzo o la compilazione di Qiskit (inclusa l'aggiunta di nuove dipendenze), ma le patch potrebbero includere supporto per nuove versioni di Python o altre dipendenze. Di solito la versione minima di una dipendenza viene aumentata soltanto quando le versioni precedenti della dipendenza non sono più supportate oppure quando non è possibile mantenere la compatibilità con l'ultima release della dipendenza e la versione precedente.

Strategia di aggiornamento

Quando viene rilasciata una nuova versione major, il percorso di aggiornamento raccomandato è quello di aggiornare prima alla versione minor più recente sulla versione major precedente. Poco prima di una nuova versione major, verrà pubblicata una versione minor finale. Questa release della versione minor finale X.Y+1.0.0 è equivalente a X.Y.0 ma con avvisi e deprecazioni per tutte le modifiche dell'API che vengono apportate nella nuova serie di versioni major.

Ad esempio, immediatamente prima della release 1.0.0, verrà pubblicata una release 0.46.0. La release 0.46.0 sarà equivalente alla release 0.45.0 ma con avvisi di deprecazione aggiuntivi che documentano le modifiche dell'API apportate come parte della release 1.0.0. Questo schema verrà utilizzato per qualsiasi futura release di versione major.

Gli utenti di Qiskit dovrebbero prima aggiornare a questa versione minor finale per vedere eventuali avvisi di deprecazione e adattare il proprio utilizzo di Qiskit prima di provare una release potenzialmente incompatibile. La versione major precedente sarà supportata per almeno sei mesi per dare tempo sufficiente per l'aggiornamento. Un metodo tipico per gestire questo è fissare la versione massima per evitare di usare la serie di release major successiva finché non sei sicuro della compatibilità. Ad esempio, specificare qiskit<2 in un file requirements quando la versione major corrente di Qiskit è 1 garantisce che tu stia utilizzando una versione di Qiskit che non presenta modifiche dell'API incompatibili.

Limitare la versione a un valore inferiore alla versione major successiva assicura che tu veda eventuali avvisi di deprecazione prima di una release major. Senza il limite, pip installa la versione più recente disponibile per impostazione predefinita.

Il formato di serializzazione QPY è compatibile con le versioni precedenti, in modo che una nuova release di Qiskit possa sempre caricare un file QPY generato con una release precedente di Qiskit. Tuttavia, il formato non è compatibile con le versioni successive, quindi, in linea di principio, non è possibile caricare file QPY generati con una versione più recente di Qiskit utilizzando una release precedente. Per facilitare la migrazione degli utenti tra release di versioni major, la funzione qiskit.qpy.dump() supporterà sempre almeno una versione in comune tra la release X.0.0 e la release X-1.Y.0 (dove Y è l'ultima versione minor di quella serie). Il parametro qiskit.qpy.dump(..., version=...) consentirà di salvare file in formato QPY che possono essere caricati da entrambe le versioni major dalla release più recente. Per maggiori dettagli consulta RFC 0020.

Pre-release

Per ogni release di versione minor e major, Qiskit pubblica pre-release che sono compatibili con PEP440. In genere si tratta di release candidate nella forma X.Y.0rc1. Le release rc avranno una superficie API definitiva e vengono usate per testare una release in preparazione.

Tieni presente che quando viene pubblicato uno dei suffissi di pre-release di PEP440 (come a, b, o pre), esso non offre le stesse garanzie di una release rc, ed è soltanto una release di anteprima. L'API potrebbe cambiare tra queste pre-release e la release finale con quel numero di versione. Ad esempio, 1.0.0pre1 potrebbe avere una API finale diversa rispetto a 1.0.0.

Post-release

Se ci sono problemi con il packaging di una release, potrebbe essere emessa una post-release per correggerli. Queste seguiranno la forma X.Y.Z.1, dove il quarto numero intero indica che si tratta della prima post-release della release X.Y.Z. Ad esempio, la release 0.25.2 di qiskit-terra (il nome legacy del pacchetto Qiskit) aveva alcuni problemi con la pubblicazione del pacchetto sdist, e fu pubblicata una post-release 0.25.2.1 che correggeva questo problema. Il codice era identico, e 0.25.2.1 correggeva soltanto il problema di packaging della release.

Come i contributori possono contrassegnare le deprecazioni

Consulta la guida alle deprecazioni nel repository dell'SDK Qiskit per le istruzioni su come aggiungere deprecazioni al codice sorgente.