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¶

The way documentation is structured in Qiskit is to push as much of the actual documentation into the docstrings as possible. This makes it easier for additions and corrections to be made during development, because the majority of the documentation lives near the code being changed.

Refer to https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html for how to create and write effective API documentation, such as setting up the RST files and docstrings.

qiskit-metapackage repository¶

Historically, Qiskit Ecosystem projects were hosted at https://qiskit.org/documentation/. Those projects now live under https://qiskit.org/ecosystem and https://qiskit.org/documentation is only for core Qiskit (aka Terra).

While we finish this migration, documentation for Qiskit is still built in https://github.com/Qiskit/qiskit-metapackage. The metapackage will Git clone Terra to pull in its API documentation, using whatever version of Terra is pinned in the setup.py. This means that fixes for incorrect API documentation will need to be included in a new release. Documentation fixes are valid backports for a stable patch release per the stable branch policy (see Política de Ramificación Estable).

This setup is temporary and we are migrating the metapackage documentation infrastructure to live in Terra. See https://github.com/Qiskit/RFCs/issues/41 to track the migration.