Estrategia de versiones del SDK de Qiskit

Los números de versión de Qiskit siguen el Versionado Semántico. El número de versión está compuesto por tres componentes principales: la versión mayor, la versión menor y la versión de parche. Por ejemplo, en el número de versión X.Y.Z, X es la versión mayor, Y es la versión menor y Z es la versión de parche.

Los cambios de API que rompen la compatibilidad se reservan para lanzamientos de versiones mayores. El período mínimo entre lanzamientos de versiones mayores es de un año. Las versiones menores introducen nuevas funcionalidades y correcciones de errores sin romper la compatibilidad de la API, y se publican periódicamente (actualmente cada tres meses) únicamente para la versión mayor actual. Las versiones de parche proporcionan correcciones de errores identificados en la versión menor más reciente de cada serie de lanzamientos activamente soportada (es decir, la versión mayor). Se soportan como máximo dos series de lanzamientos a la vez, lo cual ocurre únicamente durante el período de solapamiento que sigue a un nuevo lanzamiento de versión mayor, como se describe con más detalle a continuación.

Calendario de lanzamientos

A continuación se incluye un calendario de lanzamientos tentativo:

Para obtener un calendario de lanzamientos actualizado, consulta la lista de hitos del proyecto GitHub de Qiskit, que siempre contendrá el plan de lanzamiento actual.

Con el lanzamiento de una nueva versión mayor, la versión mayor anterior recibe soporte durante al menos seis meses con solo correcciones de errores, y un año para correcciones de seguridad. Durante este tiempo, solo se publican versiones de parche para esa versión mayor. Se publica una versión de parche final cuando se retira el soporte, y ese lanzamiento también documenta el fin del soporte para esa serie de versiones mayores. Se necesita una ventana de soporte más prolongada para la versión mayor anterior, ya que esto les da a los consumidores de Qiskit en proyectos derivados y a sus usuarios la oportunidad de migrar su código. Las bibliotecas derivadas que dependen de Qiskit no deben aumentar su versión mínima requerida de Qiskit a una nueva versión mayor inmediatamente después de su lanzamiento, porque la base de usuarios de la biblioteca necesita tiempo para migrar a los nuevos cambios de API. Contar con una ventana de soporte extendida para la versión mayor anterior de Qiskit les da a los proyectos derivados tiempo para garantizar la compatibilidad con la siguiente versión mayor. Los proyectos derivados pueden brindar soporte para dos series de lanzamientos a la vez para ofrecerle a sus usuarios una ruta de migración.

A efectos del versionado semántico, la API pública de Qiskit se considera cualquier módulo, clase, función o método documentado que no esté marcado como privado (con el prefijo de guion bajo _). Sin embargo, pueden existir excepciones explícitas para APIs documentadas específicas. En tales casos, estas APIs estarán claramente documentadas como interfaces que aún no se consideran estables, y se emitirá activamente una advertencia visible para el usuario en cualquier uso de estas interfaces inestables. Además, en algunas situaciones, una interfaz marcada como privada se considera parte de la API pública. Esto ocurre típicamente solo en dos casos: ya sea en una definición de interfaz abstracta donde las subclases deben sobreescribir/implementar un método privado como parte de la definición de una implementación de la interfaz, o en métodos de bajo nivel de uso avanzado que tienen interfaces estables pero que no se consideran seguros de usar, ya que la carga recae sobre el usuario de mantener por sí mismo los invariantes de clase y de seguridad (el ejemplo canónico de esto es el método QuantumCircuit._append).

Las versiones de Python soportadas, la versión mínima de Rust soportada (para compilar Qiskit desde el código fuente) y cualquier dependencia de paquetes de Python (incluidas las versiones mínimas soportadas de las dependencias) utilizadas por Qiskit no forman parte de las garantías de compatibilidad hacia atrás y pueden cambiar en cualquier lanzamiento. Solo los lanzamientos de versiones menores o mayores aumentarán los requisitos mínimos para usar o compilar Qiskit (incluida la adición de nuevas dependencias), pero los parches podrían incluir soporte para nuevas versiones de Python u otras dependencias. Normalmente, la versión mínima de una dependencia solo se incrementa cuando las versiones más antiguas de esa dependencia dejan de tener soporte o cuando no es posible mantener la compatibilidad con el último lanzamiento de la dependencia y la versión anterior.

Estrategia de actualización

Cuando se lanza una nueva versión mayor, la ruta de actualización recomendada es primero actualizar a la versión menor más reciente de la versión mayor anterior. Poco antes de una nueva versión mayor, se publicará una versión menor final. Este último lanzamiento de versión menor X.Y+1.0.0 es equivalente a X.Y.0 pero con advertencias y deprecaciones para cualquier cambio de API que se realice en la nueva serie de versiones mayores.

Por ejemplo, inmediatamente antes del lanzamiento de la versión 1.0.0, se publicará la versión 0.46.0. El lanzamiento 0.46.0 será equivalente al lanzamiento 0.45.0 pero con advertencias de deprecación adicionales que documentan los cambios de API realizados como parte del lanzamiento 1.0.0. Este patrón se utilizará para cualquier futuro lanzamiento de versión mayor.

Los usuarios de Qiskit deben primero actualizar a esta versión menor final para ver cualquier advertencia de deprecación y ajustar su uso de Qiskit antes de intentar un lanzamiento que puede ser incompatible. La versión mayor anterior tendrá soporte durante al menos seis meses para dar tiempo suficiente para actualizar. Un patrón típico para gestionar esto es fijar la versión máxima para evitar usar la siguiente serie de versiones mayores hasta que estés seguro de la compatibilidad. Por ejemplo, especificar qiskit<2 en un archivo de requisitos cuando la versión mayor actual de Qiskit es 1 garantiza que estás usando una versión de Qiskit que no tiene cambios de API que rompan la compatibilidad.

Limitar la versión a menos que la siguiente versión mayor garantiza que veas cualquier advertencia de deprecación antes de un lanzamiento de versión mayor. Sin ese límite, pip instala la versión más reciente disponible de forma predeterminada.

El formato de serialización QPY es compatible hacia atrás, de modo que un nuevo lanzamiento de Qiskit siempre puede cargar un archivo QPY generado con una versión anterior de Qiskit. Sin embargo, el formato no es compatible hacia adelante, por lo que, en principio, no es posible cargar archivos QPY generados con una versión más nueva de Qiskit usando una versión anterior. Para facilitar la migración de usuarios entre lanzamientos de versiones mayores, la función qiskit.qpy.dump() siempre soportará al menos una versión superpuesta entre el lanzamiento X.0.0 y el lanzamiento X-1.Y.0 (donde Y es la última versión menor de esa serie). El parámetro qiskit.qpy.dump(..., version=...) permitirá guardar archivos en formato QPY que puedan ser cargados por ambas versiones mayores desde el lanzamiento más nuevo. Consulta más detalles en RFC 0020.

Versiones previas al lanzamiento

Para cada lanzamiento de versión menor y mayor, Qiskit publica versiones previas al lanzamiento que son compatibles con PEP440. Normalmente, estas son candidatas de lanzamiento de la forma X.Y.0rc1. Los lanzamientos rc tendrán una superficie de API finalizada y se usan para probar un lanzamiento prospectivo.

Ten en cuenta que cuando se publican uno de los sufijos de versión previa al lanzamiento de PEP440 (como a, b o pre), este no tiene las mismas garantías que un lanzamiento rc, y es solo una versión de vista previa. La API podría cambiar entre estas versiones previas al lanzamiento y el lanzamiento final con ese número de versión. Por ejemplo, 1.0.0pre1 podría tener una API final diferente a la de 1.0.0.

Versiones posteriores al lanzamiento

Si hay problemas con el empaquetado de un lanzamiento, se puede publicar una versión posterior al lanzamiento para corregirlo. Estas seguirán la forma X.Y.Z.1, donde el cuarto entero indica que es la primera versión posterior al lanzamiento X.Y.Z. Por ejemplo, el lanzamiento 0.25.2 de qiskit-terra (el nombre de paquete heredado para Qiskit) tuvo algún problema con la publicación del paquete sdist, y se publicó una versión posterior al lanzamiento 0.25.2.1 que corrigió ese problema. El código era idéntico, y 0.25.2.1 solo corrigió el problema de empaquetado del lanzamiento.

Cómo los colaboradores pueden marcar deprecaciones

Consulta la guía de deprecaciones en el repositorio del SDK de Qiskit para obtener instrucciones sobre cómo agregar deprecaciones al código fuente.