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 está modificando.
Consulta https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html para obtener información sobre cómo crear y escribir documentación eficaz de API, como la configuración de archivos RST y docstrings.
Repositorio qiskit-metapackage¶
Históricamente, los proyectos del Ecosistema Qiskit se alojaban en https://qiskit.org/documentation/. Esos proyectos ahora se encuentran en https://qiskit.org/ecosystem y https://qiskit.org/documentation es solo para el núcleo de Qiskit (también conocido como Terra).
Mientras finalizamos esta migración, la documentación para Qiskit aún está construida en https://github.com/Qiskit/qiskit-metapackage. El metapaquete hará que hacer Git clone a Terra obtenga su documentación de la API, usando cualquier versión de Terra que esté anclada en setup.py. Esto significa que las correcciones para la documentación de la API incorrecta deberán incluirse en una nueva versión. Las correcciones de documentación son adaptaciones válidas para una liberación de parche estable según la política de rama estable (ver Política de Ramificación Estable).
Esta configuración es temporal y estamos migrando la infraestructura de la documentación del metapaquete para que viva en Terra. Consulta https://github.com/Qiskit/RFCs/issues/41 para realizar un seguimiento de la migración.