Stratégie de versionnement du SDK Qiskit
Les numéros de version de Qiskit suivent le Versionnement Sémantique.
Le numéro de version est composé de trois composantes principales : les versions majeure, mineure et
corrective. Par exemple, dans le numéro de version X.Y.Z, X est la version majeure,
Y est la version mineure, et Z est la version corrective.
Les changements d'API incompatibles sont réservés aux versions majeures. La période minimale entre deux versions majeures est d'un an. Les versions mineures introduisent de nouvelles fonctionnalités et des corrections de bugs sans rompre la compatibilité de l'API, et sont publiées périodiquement (actuellement tous les trois mois) uniquement pour la version majeure actuelle. Les versions correctives fournissent des correctifs pour les bugs identifiés dans la version mineure la plus récente de chaque série de versions activement supportée (c'est-à-dire la version majeure). On supporte au maximum deux séries de versions à la fois, ce qui se produit uniquement pendant la période de chevauchement qui suit la publication d'une nouvelle version majeure, décrite plus en détail ci-dessous.
Calendrier de publication
Un calendrier de publication indicatif est inclus ci-dessous :
Pour un calendrier de publication à jour, réfère-toi à la liste des jalons du projet GitHub Qiskit, qui contiendra toujours le plan de publication actuel.
Avec la publication d'une nouvelle version majeure, la version majeure précédente est supportée pendant au moins six mois avec uniquement des corrections de bugs, et un an pour les correctifs de sécurité. Pendant cette période, seules des versions correctives sont publiées pour cette version majeure. Une version corrective finale est publiée lorsque le support prend fin, et cette version documente également la fin du support pour cette série de versions majeures. Une fenêtre de support plus longue est nécessaire pour la version majeure précédente, car cela donne aux consommateurs en aval de Qiskit et à leurs utilisateurs la possibilité de migrer leur code. Les bibliothèques en aval qui dépendent de Qiskit ne devraient pas relever leur version minimale requise de Qiskit vers une nouvelle version majeure immédiatement après sa publication, car la base d'utilisateurs de la bibliothèque a besoin de temps pour migrer vers les nouveaux changements d'API. Disposer d'une fenêtre de support étendue pour la version majeure précédente de Qiskit donne aux projets en aval le temps de s'assurer de la compatibilité avec la version majeure suivante. Les projets en aval peuvent fournir un support pour deux séries de versions à la fois afin d'offrir à leurs utilisateurs un chemin de migration.
Aux fins du versionnement sémantique, l'API publique de Qiskit est considérée comme
tout module, classe, fonction ou méthode documenté qui n'est pas marqué comme privé
(avec le préfixe underscore _). Cependant, des exceptions explicites peuvent être faites pour
des API documentées spécifiques. Dans ces cas, ces API seront clairement documentées
comme n'étant pas encore considérées comme des interfaces stables, et un avertissement visible par l'utilisateur sera
activement émis lors de toute utilisation de ces interfaces instables. De plus, dans certaines
situations, une interface marquée comme privée est considérée comme faisant partie de l'API publique.
Cela se produit généralement dans deux cas seulement : soit une définition d'interface abstraite
où les sous-classes sont censées redéfinir/implémenter une méthode privée
dans le cadre de la définition d'une implémentation de l'interface, soit des méthodes bas niveau
à usage avancé qui ont des interfaces stables mais ne sont pas considérées comme sûres à utiliser,
car la charge incombe à l'utilisateur de respecter lui-même les invariants de classe/sécurité
(l'exemple canonique est la méthode QuantumCircuit._append).
Les versions Python supportées, la version minimale supportée de Rust (pour compiler Qiskit depuis les sources), et toutes les dépendances de paquets Python (y compris les versions minimales supportées des dépendances) utilisées par Qiskit ne font pas partie des garanties de compatibilité descendante et peuvent changer lors de n'importe quelle version. Seules les versions mineures ou majeures augmenteront les exigences minimales pour utiliser ou compiler Qiskit (y compris l'ajout de nouvelles dépendances), mais les correctifs pourraient inclure un support pour de nouvelles versions de Python ou d'autres dépendances. Généralement, la version minimale d'une dépendance n'est augmentée que lorsque les anciennes versions de cette dépendance ne sont plus supportées ou lorsqu'il n'est pas possible de maintenir la compatibilité avec la dernière version de la dépendance et l'ancienne version.
Stratégie de mise à niveau
Lorsqu'une nouvelle version majeure est publiée, le chemin de mise à niveau recommandé
est de d'abord mettre à niveau vers la version mineure la plus récente de la version majeure précédente.
Peu avant une nouvelle version majeure, une version mineure finale sera
publiée. Cette version mineure finale X.Y+1.0.0 est équivalente à
X.Y.0 mais avec des avertissements et des dépréciations pour tout changement d'API effectué
dans la nouvelle série de versions majeures.
Par exemple, immédiatement avant la publication de la version 1.0.0, une version 0.46.0 sera publiée. La version 0.46.0 sera équivalente à la version 0.45.0 mais avec des avertissements de dépréciation supplémentaires qui documentent les changements d'API effectués dans le cadre de la version 1.0.0. Ce schéma sera utilisé pour toute future publication de version majeure.
Les utilisateurs de Qiskit devraient d'abord mettre à niveau vers cette version mineure finale
pour voir les éventuels avertissements de dépréciation et ajuster leur utilisation de Qiskit
avant d'essayer une version potentiellement incompatible. La version
majeure précédente sera supportée pendant au moins six mois pour laisser suffisamment de temps
pour effectuer la mise à niveau. Un schéma typique pour gérer cela est de fixer la version maximale afin
d'éviter d'utiliser la série de versions majeures suivante jusqu'à ce que tu sois sûr de la compatibilité.
Par exemple, spécifier qiskit<2 dans un fichier requirements lorsque la version
majeure actuelle de Qiskit est 1 garantit que tu utilises une version de Qiskit
qui n'a pas de changements d'API incompatibles.
Plafonner la version en dessous de la prochaine version majeure
garantit que tu vois les avertissements de dépréciation avant une
publication de version majeure.
Sans ce plafond, pip installe
la version la plus récente disponible par défaut.
Le format de sérialisation QPY est rétrocompatible, de sorte qu'une nouvelle version de Qiskit peut toujours charger un fichier QPY
généré avec une version antérieure de Qiskit. Cependant, le format n'est pas compatible en avant, donc, en principe, il n'est pas possible
de charger des fichiers QPY générés avec une version plus récente de Qiskit en utilisant une version plus ancienne. Pour faciliter la migration des utilisateurs entre les versions majeures, la fonction qiskit.qpy.dump() supportera toujours au moins une version commune entre la version X.0.0 et la version X-1.Y.0 (où Y est la dernière version mineure de
cette série). Le paramètre qiskit.qpy.dump(..., version=...) permettra d'enregistrer des fichiers au format QPY qui peuvent être chargés par les deux versions majeures depuis la version la plus récente.
Voir plus de détails dans la RFC 0020.
Pré-versions
Pour chaque version mineure et majeure, Qiskit publie des pré-versions qui
sont compatibles avec PEP440. Typiquement,
ce sont des candidats à la version de la forme X.Y.0rc1. Les versions rc
auront une surface d'API finalisée et sont utilisées pour tester une version candidate.
Note que lorsque l'un des suffixes de pré-version PEP440 (comme a, b, ou pre) est
publié, il n'a pas les mêmes garanties qu'une version rc, et n'est
qu'une version préliminaire. L'API pourrait changer entre ces pré-versions
et la version finale portant ce numéro de version. Par exemple, 1.0.0pre1 pourrait avoir
une API finale différente de 1.0.0.
Post-versions
Si des problèmes surviennent avec le packaging d'une version, une post-version pourrait être
publiée pour les corriger. Ces versions suivront la forme X.Y.Z.1 où le quatrième
entier indique qu'il s'agit de la première post-version de la version X.Y.Z.
Par exemple, la version 0.25.2 de qiskit-terra (le nom de paquet hérité de Qiskit)
avait un problème avec la publication du paquet sdist, et une post-version
0.25.2.1 a été publiée pour corriger ce problème. Le code était identique, et
0.25.2.1 n'a corrigé que le problème de packaging de la version.
Comment les contributeurs peuvent marquer les dépréciations
Réfère-toi au guide de dépréciation dans le dépôt du SDK Qiskit pour des instructions sur la façon d'ajouter des dépréciations au code source.