Guide des mainteneurs¶

Ce document définit un * maintainer * comme un contributeur disposant de privilèges de fusion. Les informations détaillées ici sont principalement liées aux versions de Qiskit et aux autres processus internes.

Politique de la branche stable¶

La branche dite stable est la source saine des différentes corrections des anomalies majeures identifies et corrigées dans le master depuis la dernière version. Toute modification de cette branche stable doit se faire en évaluant en premier le risque lié à la modification et en le comparant au bénéfices obtenus. Seuls quelques changements bien identifiés doivent être inclus dans cette branche stable. Une correction majeure mais adressant une anomalie critique ou bien une correction triviale pour une fonctionnalité très mineure peuvent être considérées. Dans tous les cas, il est bon de considérer les points suivants :

Le risque de régression : même la plus petite des modifications peut avoir un impact sur la stabilité du code. Et l’objectif est bien entendu de garder la branche stable la plus sûre possible.
Le bénéfice utilisateur : sommes-nous en train de corriger quelque chose constaté par les utilisateurs ? Cela apporte-t-il un réel gain pour eux ?
La portée de la correction : si cette correction règle un problème important, mais qu’elle engendre des modifications fortes du code, il doit être envisagé d’imaginer une correction plus légère.
La correction est-elle déjà dans le Master ? Une modification peut être le rétroportage d’une correction déjà présente dans le Master, ou bien la correction n’a peut-être aucun sens dans le Master.

Procédure de rétroportage (Backporting) :¶

Lorsqu’une correction est réalisée du Master vers la branche stable, il est important d’en garder la trace dans le Master. Lorsque vous créez la branche recevant la PR stable, utilisez la commande:

$ git cherry-pick -x $master_commit_id

Bien entendu, cette méthode ne fonctionne que pour les correctifs simples issus du Master. Si vous devez rétroporter (backport) un ensemble conséquent de modifications (commits), issues du Master, faite le manuellement. Dans ce cas, ajoutez

Backported from: #master pr number

pour que nous puissions suivre la source du sous-ensemble des modifications, même si un cherry-pick strict n’a pas de sens.

Si la mise à jour que vous proposez ne va pas choisir le correctif, vous pouvez aider en résolvant vous-même les conflits et en proposant le correctif qui en résulte. Veuillez conserver les lignes de conflit dans le message de commit pour aider à revoir le correctif stable.

Étiquettes de rétroportage¶

Les anomalies ou PR avec l’étiquette stable backport potential sont celles candidates à un backportage dans le Master. Une fois l’intégration réalisée, l’étiquette doit être supprimée.

Ajoutez [Stable] dans le titre de la PR envoyée à la branche stable pour confirmer la pertinence de cette PR. N’oubliez pas d’ajouter le numéro de la PR dans le Master.

Gestion des versions de Qiskit¶

Le projet Qiskit est constitué de plusieurs éléments couvrant différentes fonctionnalités. Chacun des éléments a son utilité et peut être utilisé de manière indépendante, mais pour faciliter les choses nous fournissons une source et un meta-package servant de point d’entrée et permettant d’installer tous les éléments en une seule fois. Il s’agit de simplifier le processus d’installation et d’offrir une interface unique aux utilisateurs. Cependant dans la mesure ou chacun des éléments a ses propres versions, il faut apporter un minimum d’attention lorsque l’on gère les différentes versions de chacun des éléments. Ce document souligne les lignes directrices à observer pour gérer les différentes versions des éléments, et le meta-package.

Pour la suite de ce guide, la nomenclature standard de la gestion de version est la suivante Majeure.Mineure.Correctif pour référencer les différentes composantes du numéro de version. Par exemple si le numéro de version est 0.7.1, alors la version majeure est 0, la version mineure est 7, et le niveau de correctif est 1.

Version du Meta-package¶

La version du meta-package de Qiskit est une valeur indépendante qui est déterminée par les versions de chacun des éléments qui le constituent. A chaque fois que la mise mise à jour d’un élément est publiée (ou qu’un élément est ajouté), la définition du contenu du méta-package sera mise à jour et sa version sera changée. Les calendriers de mise à jours seront coordonnés pour s’assurer que les publications du méta-package sont consistantes avec la mise à jour des éléments.

Ajout de nouveaux éléments tracés¶

Lorsqu’un élément de Qiskit est mis à jour ou ajouté et qu’il modifie les dépendances, nous augmentons la version Mineure du meta-package.

Par exemple supposons que le meta-package suit deux éléments qiskit-aer``et ``qiskit-terra et que sa version est 0.7.4. Ensuite nous publions le nouvel élément qiskit-ignis que nous voulons aussi suivre dans le meta-package, alors nous passons la version du meta-package à 0.8.0.

Incrément des version de correction¶

Lorsqu’un élément de Qiskit déjà suivi dans le méta-package fait l’objet d’une modification pour corriger des problèmes, alors les exigences doivent apparaître dans le fichier setup.py et cela va incrémenter la version du méta-package.

Par exemple, supposons que le méta-package suit 2 éléments qiskit-terra==0.8.1 et qiskit-aer==0.2.1, à la version 0.9.6. Lorsque qu’une correction sera apportée à qiskit-terra pour corriger un problème, ce dernier passera à la version 0.8.2, le méta-package sera également incrémenté et son niveau deviendra 0.9.7.

De plus, il y a parfois des paquets ou d’autres bogues dans le méta-paquet lui-même qui doivent être corrigés en poussant les nouvelles versions. Quand ceci se produit, nous devrions augmenter la version de patch pour la différencier de la version buggée. Ne supprimez pas les versions buggées ou anciennes de Pypi , en aucun cas, à la place augmentez simplement la version du patch et téléchargez une nouvelle version.

Incrément des version Mineures¶

De plus lorsqu’un nouvel élément est ajouté au métapackage, la version mineure du métapackage devrait également être augmentée chaque fois qu’une version mineure est augmentée parmi les éléments suivis.

Par exemple supposons que le meta-package suit les deux éléments qiskit-terra==0.7.0 et qiskit-aer==0.1.1, et que sa version courante est 0.7.5. Lorsque la version de qiskit-aer passe à 0.2.0 alors la version du méta-package va passer à 0.8.0.

Incrément de version majeure¶

La version majeure est gérée de manière un peu différente des autres composantes constituant la gestion des version, lesquelles sont modifiées selon les changement de version des composants. La version majeure n’est changée que lors d’un changement de version de tous les composants (du moins avant la version 1.0.0). Actuellement tous les composants on un niveau de majeur 0``et tant qu'ils ne seront pas tous marqués comme ayant atteint une version stable (donc à une version majeure ``>=1) alors le métapackage ne peut pas passer à la version majeure suivante.

La règle de changement de version majeure du meta-package après que tous les composants soient à une version >=1.0.0 n’est pas encore déterminée.

Options supplémentaires¶

En plus des éléments suivis, il y a des paquets supplémentaires construits au dessus de Qiskit et qui sont développés en marge de Qiskit par exemple les référentiels d’application comme qiskit-optimization. Pour des raisons pratiques ces paquets sont suivis par le métapaquet Qiskit comme des suppléments facultatifs pouvant être installés avec Qiskit. Les versions de ces projets facultatifs n’ont pas d’effet sur le métapackage car elles n’y sont pas liées. S’il y a un problème de compatibilité entre Qiskit et ces dépendances optionnelles et que la version minimale doit être ajustée par une version autonome, cela sera fait par la publication d’un correctif.

Exigences de suivi des éléments d Qiskit¶

Bien que ce ne soit pas strictement relié à la gestion des versions du méta-package et de Qiskit, la manière dont nous suivons les versions des éléments dans les exigences du méta-package est importante. Chacun des éléments listés dans setup.py devrait correspondre à une version unique. Ceci signifie que chaque version de Qiskit ne définit qu’une seule version de chacun de ses éléments. Par exemple, la liste des exigences devrait toujours être de la forme:

requirements = [
    "qiskit_terra==0.7.0",
    "qiskit-aer==0.1.1",
]

Ceci est conçu de manière à aider au déboggage, mais aussi pour faciliter le suivi des versions pour l’ensemble des éléments.

Structure de la Documentation¶

La façon dont la documentation est structurée dans Qiskit est de la faire figurer autant que possible la documentation réelle dans les « docstring ». Il est ainsi plus facile de faire des ajouts et des corrections au cours du développement, car la majorité de la documentation se trouve près du code modifié. Il y a trois niveaux dans la structure de documentation normale à Terra :

Les fichiers .rst``dans le répertoire ``docs/apidocs

These files are used to tell Sphinx which modules to include in the rendered documentation. This contains two pieces of information: an internal reference or cross reference to the module, which can be used for internal links inside the documentation, and an automodule directive used to parse the module docstrings from a specified import path. For example, the dagcircuit.rst file contains:

.. _qiskit-dagcircuit:


.. automodule:: qiskit.dagcircuit
   :no-members:
   :no-inherited-members:
   :no-special-members:

Le fichier qiskit.rst est différent et contient la table des matières. Si vous créez un fichier .rst pour documenter un nouveau module, assurez-vous de l’ajouter au fichier toctree.

Le docstring au niveau du module

Ce dosctring est au niveau du module pour le module spécifié dans la directive automodule dans le fichier rst. Si le module spécifié est un répertoire / espace de nom, la chaîne de caractères doit être spécifiée dans le fichier __init__.py pour ce répertoire. Ce docstring de niveau module contient plus de détails sur le module en cours de documentation. La structure normale de cette chaîne de caractères consiste à décrire toutes les classes et toutes les fonctions de l’API publique contenues dans ce module. Ceci est généralement effectué à l’aide de la directive « autosummary » <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>` __ (ou » autodoc directives <http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>` __ directement si le module est simple, comme dans le cas de qiskit.execute). La directive autosummary est utilisée pour autodocumenter une liste de différents éléments Python (classes, fonctions, etc.) directement sans avoir à appeler manuellement les directives autodoc pour chacune d’elles. La chaîne docstring de niveau module permet de fournir une présentation générale de la fonctionnalité fournie par le module. Cela se fait normalement en regroupant les différentes composantes de l’API publique en plusieurs sous-sections.

Par exemple, pour le module dagcircuit déjà évoqué, le contenu du docstring dans qiskit/dagcircuit/__init__.py serait:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================

.. currentmodule:: qiskit.dagcircuit

DAG Circuits
============

.. autosummary::
   :toctree: ../stubs/

   DAGCircuit
   DAGNode

Exceptions
==========

.. autosummary::
   :toctree: ../stubs/

   DAGCircuitError
"""

Note

Ce n’est qu’un exemple et le module docstring pour le module dagcircuit peut en réalité être différent.

La chaîne de docstring réelle des éléments répertoriés dans la docstring du module

Vous devez absolument documenter toutes les interfaces publiques, en utilisant des exemples si nécessaire. Pour les docstrings, sont utilisés les Google Python Style Docstrings Le parsing est réalisé par la napoleon sphinx extension. L`extension sphinx napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__ contient de bons exemples de docstrings correctement formatés.

Note

Vous pouvez utiliser toute directive Sphinx ou format de rst si cela a du sens. Par exemple, une extension couramment utilisée est la directive jupyter-execute employée pour executer un bloc de code Jupyter et afficher à la fois le code et le résultat. Ceci est particulièrement utile lorsqu’il s’agit de visualisations.

Intégration de la documentation¶

La documentation dans https://qiskit.org/documentation/ couvre l’intégralité du projet Qiskit. Terra n’est qu’une partie de ce projet. Les builds de cette documentation sont produits par le meta-package Qiskit https://github.com/Qiskit/qiskit. Lorsque les Commits sont rassemblés dans ce répertoire, les builds Sphinx sont chargés dans le site web qiskit.org. Ces builds Sphinx sont configurés pour pousser la documentation dans la version définie dans les metapackages. Par exemple, si la version des metapackages est toujours la 0.13.0, la documentation est issue de la version 0.10.0 de Terra. La documentation est poussée depuis la nouvelle version lorsque les meta-packages évoluent. Cela implique que les corrections faites à la documentation d’une API doivent être incluses dans une nouvelle version. Ces corrections sont des rétroportages d’une version stable, conforme à la politique de branche stable (voir ci-dessous Politique de la branche stable).

Pendant le processus de build, le contenu de docs/apidocs/ est copié dans une version partagée de doc/apidocs/ dans le répertoire du métapackage, en même temps que tous les autres éléments. Le contenu intégral de docs/apidocs se retrouvera donc à la racine de https://qiskit.org/documentation/apidoc/.