Spanish
Languages
English
Bengali
French
German
Japanese
Korean
Portuguese
Spanish
Tamil

Guía de Mantenedores

Este documento define a un mantenedor como un colaborador con privilegios de fusión (merge). La información detallada aquí está relacionada principalmente con las liberaciones de Qiskit y otros procesos internos.

Política de Ramificación Estable

La rama estable está destinada a ser una fuente segura de correcciones para errores de alto impacto y problemas de seguridad que se han solucionado en master desde su liberación. Al revisar un PR de rama estable, debemos equilibrar el riesgo de cualquier parche dado con el valor que proporcionará a los usuarios de la rama estable. Solo una clase limitada de cambios es apropiada para su inclusión en la rama estable. Un parche grande y arriesgado para un problema importante podría tener sentido, al igual que una solución trivial para un caso de manejo de errores bastante oscuro. Se deben tomar en cuenta varios factores al considerar un cambio:

  • El riesgo de regresión: incluso los cambios más pequeños conllevan algún riesgo de romper algo, y realmente queremos evitar regresiones en la rama estable.

  • El beneficio de visibilidad para el usuario: ¿estamos arreglando algo que los usuarios podrían notar? y, de ser así, ¿qué tan importante es?

  • Qué tan autónoma es la solución: si soluciona un problema importante, pero también refactoriza una gran cantidad de código, probablemente valga la pena pensar en cómo se vería una solución menos riesgosa.

  • Si la corrección ya está en master: un cambio debe ser un backport de un cambio ya fusionado en master, a menos que el cambio simplemente no tenga sentido en master.

Procedimiento de adaptación a versiones anteriores (backporting):

Al adaptar un parche de la rama master a una rama estable, queremos mantener una referencia del cambio en master. Cuando crees la rama para el PR estable, usa:

$ git cherry-pick -x $master_commit_id

Sin embargo, esto solo funciona para pequeños parches autónomos de master. Si necesitas exportar un subconjunto de un commit más grande (de un PR compactado, por ejemplo) de master, hazlo manualmente. En estos casos, agrega:

Backported from: #master pr number

para que podamos rastrear la fuente del subconjunto de cambios, incluso si una selección puntual (cherry-pick) no tiene sentido.

Si el parche que estás proponiendo no se puede seleccionar puntualmente (cherry-pick) de manera limpia, puedes ayudar resolviendo los conflictos tu mismo y proponiendo el parche resultante. Mantén las líneas de Conflictos en el mensaje de confirmación (commit) para ayudar a revisar el parche estable.

Etiquetas de backport

Los errores o PRs etiquetados con stable backport potential son errores que también se aplican a la versión estable y pueden ser adecuados para el backporting una vez que una corrección llega a master. Una vez que se ha propuesto el backport, se debe quitar la etiqueta.

Incluye [Stable] en el título del PR hacia la rama estable, como una señal de que establecer la rama objetivo como estable no fue un error. Además, haz referencia al número del PR en master del que se está transfiriendo.

Control de Versiones de Qiskit

El proyecto Qiskit se compone de varios elementos, cada uno de los cuales realiza una funcionalidad diferente. Cada uno es útil de forma independiente y se puede utilizar por sí solo, pero para mayor comodidad proporcionamos este repositorio y metapaquete para proporcionar un único punto de entrada para instalar todos los elementos a la vez. Esto es para simplificar el proceso de instalación y proporcionar una interfaz unificada a los usuarios finales. Sin embargo, debido a que cada elemento de Qiskit tiene sus propias liberaciones y versiones, es necesario tener cuidado al tratar con versiones entre los diferentes repositorios. Este documento describe las pautas para tratar con versiones y liberaciones tanto de los elementos de Qiskit como del metapaquete.

Para el resto de esta guía, se utilizará la nomenclatura estándar de versiones semánticas de: Major.Minor.Patch para hacer referencia a los diferentes componentes de un número de versión. Por ejemplo, si el número de versión es 0.7.1, entonces la versión principal es 0, la versión menor es 7 y la versión del parche es 1.

Versión del Metapaquete

La versión del metapaquete de Qiskit es un valor independiente que está determinado por las versiones de cada uno de los elementos que está siendo rastreado. Cada vez que enviamos una versión a un componente rastreado (o agregamos un elemento), los requisitos del metapaquete y la versión deberán actualizarse y publicarse una nueva versión. El tiempo debe coordinarse con el lanzamiento de elementos para garantizar que los lanzamientos de metapaquetes se realicen con los lanzamientos de elementos.

Adición de Nuevos Elementos Rastreados

Cuando se agrega un nuevo elemento Qiskit a los requerimientos del metapaquete, necesitamos aumentar la versión Minor del metapaquete.

Por ejemplo, si el metapaquete está rastreando los 2 elementos qiskit-aer y qiskit-terra y su versión es 0.7.4. Luego liberamos un nuevo elemento qiskit-new que pretendemos incluir también en el metapaquete. Entonces cuando agregamos el nuevo elemento al metapaquete, aumentamos la versión a 0.8.0.

Incremento de la Versión del Parche

Cuando cualquier elemento de Qiskit que ya está siendo rastreado por el metapaquete lanza una versión de parche para corregir errores en una liberación, también necesitamos aumentar el requerimiento en setup.py y luego aumentar la versión del parche del metapaquete.

Por ejemplo, si el metapaquete está rastreando los 3 elementos qiskit-terra==0.8.1, qiskit-aer==0.2.1, con la versión actual 0.9.6. Cuando qiskit-terra lance una nueva versión de parche para corregir un error 0.8.2, el metapaquete también deberá aumentar su versión de parche y su liberación, convirtiéndose en 0.9.7.

Además, ocasionalmente hay empaquetados u otros errores en el metapaquete en sí que deben corregirse provocando nuevas versiones. Cuando se encuentren, deberíamos aumentar la versión del parche para diferenciarla de la liberación rota. No elimines las versiones rotas o antiguas de pypi en cualquier situación, en su lugar, simplemente aumenta la versión del parche y carga una nueva versión.

Incremento de la Versión Menor

Además, cuando se agrega un nuevo elemento al metapaquete, la versión menor del metapaquete también debe aumentarse cada vez que se aumente una versión menor en un elemento rastreado.

Por ejemplo, si el metapaquete está rastreando los 2 elementos qiskit-terra==0.7.0 y qiskit-aer==0.1.1 y la versión actual es 0.7.5. Cuando el elemento qiskit-aer libere 0.2.0, entonces necesitamos aumentar la versión del metapaquete para que sea 0.8.0 para que corresponda con la nueva versión.

Incremento de la Versión Mayor

La versión principal (o mayor) es diferente del número de versión de los demás componentes. A diferencia de los números de versión de los otros componentes, que son actualizados al mismo tiempo con cada elemento rastreado, la versión principal solo aumenta cuando se modifican todas las versiones rastreadas (al menos antes de 1.0.0). En este momento, todos los elementos todavía tienen un número de versión principal de componente 0 y hasta que cada elemento rastreado en el meta-repositorio sea marcado como estable, al hacer que la versión principal sea >=1, entonces la versión del metapaquete no debería aumentar la versión principal (o mayor).

Aún no se ha decidido el comportamiento del seguimiento del componente del número de versión principal después de que todos los elementos sean >=1.0.0.

Extras Opcionales

Además de los elementos rastreados, hay paquetes adicionales construidos sobre Qiskit que se desarrollan en conjunto con Qiskit, por ejemplo, los repositorios de aplicaciones como qiskit-optimization. Para mayor comodidad, el metapaquete Qiskit realiza un seguimiento de estos paquetes como extras opcionales que se pueden instalar con Qiskit. Las versiones de estos proyectos downstream opcionales no provocan una liberación del metapaquete, ya que no están fijadas y no afectan a la versión del metapaquete. Si hay un problema de compatibilidad entre Qiskit y estas dependencias downstream opcionales, la versión mínima debe ajustarse en una liberación independiente, esto solo se hará como una liberación de parche, ya que es una corrección de errores de empaquetamiento.

Seguimiento de Requerimientos de Elementos de Qiskit

Si bien no está estrictamente relacionado con el metapaquete y el control de versiones de Qiskit, la forma en que rastreamos las versiones de los elementos en la lista de requerimientos del metapaquete es importante. Cada elemento enumerado en el archivo setup.py debe estar fijado a una única versión. Esto significa que cada versión de Qiskit solo debe instalar una única versión para cada elemento rastreado. Por ejemplo, la lista de requerimientos en un punto dado debería tener un aspecto similar a:

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

Esto es para ayudar en la depuración, pero también hace que el seguimiento de las versiones en varios elementos sea más transparente.

Estructura de la Documentación

La forma en que la documentación está estructurada en Qiskit es buscar tener la mayor cantidad de la documentación en docstrings como sea posible. Esto facilita que se realicen adiciones y correcciones durante el desarrollo, porque la mayoría de la documentación se encuentra cerca del código que se cambia. Hay tres niveles en la estructura de documentación normal en Terra:

Los archivos .rst en docs/apidocs

Estos archivos se utilizan para decirle a Sphinx qué módulos incluir en la documentación renderizada. Esto contiene dos piezas de información: una referencia interna o una referencia cruzada al módulo, que se puede usar para enlaces internos dentro de la documentación, y una directiva automódulo que se utiliza para analizar las docstrings del módulo desde una ruta de importación especificada. Por ejemplo, el archivo dagcircuit.rst contiene:

.. _qiskit-dagcircuit:


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

El único archivo .rst fuera de este es qiskit.rst, que contiene la tabla de contenido. Si estás agregando un nuevo archivo .rst para la documentación de un nuevo módulo, asegúrate de agregarlo al toctree en ese archivo.

La docstring a nivel de módulo

Esta cadena de documentación (docstring) está a nivel de módulo para el módulo especificado en la directiva automodule en el primer archivo. Si el módulo especificado es un directorio/espacio de nombres (namespace), la docstring debe especificarse en el archivo __init__.py para ese directorio. Esta docstring a nivel de módulo contiene más detalles sobre el módulo que se está documentando. La estructura normal de esta docstring es describir todas las clases y funciones de la API pública contenidas en ese módulo. Esto se hace típicamente usando la directiva autosummary (o directivas autodoc directamente si el módulo es simple, como en el caso de qiskit.execute). La directiva autosummary se usa para autodocumentar (autodoc) una lista de diferentes elementos de Python (clases, funciones, etc.) directamente sin tener que llamar manualmente las directivas autodoc para cada uno. La cadena de documentación a nivel de módulo es donde se proporciona una descripción general de alto nivel de las funciones que proporciona el módulo. Esto se hace normalmente agrupando los diferentes componentes de la API pública en múltiples subsecciones.

Por ejemplo, como en el caso anterior del módulo dagcircuit, los contenidos de la docstring del módulo para qiskit/dagcircuit/__init__.py serían:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================
.. currentmodule:: qiskit.dagcircuit
DAG Circuits
============
.. autosummary::
   :toctree: ../stubs/
   DAGCircuit
   DAGNode
Exceptions
==========
.. autosummary::
   :toctree: ../stubs/
   DAGCircuitError
"""

Nota

Esto es solamente un ejemplo y la docstring real para el módulo dagcircuit podría diferir.

La docstring real para los elementos listados en la docstring del módulo

Deberías esforzarte por documentar a fondo todas las interfaces públicas expuestas utilizando ejemplos cuando sea necesario. Para las cadenas de documentación, se utilizan las Google Python Style Docstrings. Esto se analiza utilizando la extensión napoleon sphinx. La documentación de napoleon contiene un buen ejemplo de cómo deben formatearse las cadenas de documentación.

Nota

Puedes usar cualquier directiva de Sphinx o del formato rst en una docstring mientras sea razonable. Por ejemplo, una extensión comúnmente usada es la directiva jupyter-execute, que se utiliza para ejecutar un bloque de código en Jupyter y mostrar tanto el código como su salida. Esto es particularmente útil para las visualizaciones.

Integración de la Documentación

La documentación alojada en https://qiskit.org/documentation/ cubre todo el proyecto Qiskit; Terra es solo un componente de eso. Como tal, la documentación generada para la versión alojada está construida desde el repositorio de metapaquetes de Qiskit https://github.com/Qiskit/qiskit. Cuando los commits son fusionados con ese repositorio, la salida de las compilaciones de Sphinx se carga en el sitio web qiskit.org. Esas construcciones de Sphinx están configuradas para extraer la documentación de la versión de los elementos Qiskit instalados por el metapaquete en ese momento. Por ejemplo, si la versión del metapaquete es actualmente 0.13.0, entonces se copiará la documentación de la versión 0.10.0 de Terra. Cuando los requerimientos del metapaquete son incrementados, entonces comenzará a extraer documentación de la nueva versión. Esto significa que las correcciones para la documentación incorrecta de la API deberán incluirse en una nueva versión. Las correcciones de documentación son backports válidos para una versión de parche estable según la política de rama estable (consulta Política de Ramificación Estable).

Durante el proceso de generación, los contenidos de cada elemento de docs/apidocs/ son recursivamente duplicados en una copia compartida de doc/apidocs/ en el repositorio del metapaquete junto con todos los otros elementos. Esto significa que lo que haya en esta raíz docs/apidocs de cada elemento en una versión acabará estando en la raíz de https://qiskit.org/documentation/apidoc/.