Saltar al contenido principal

Lanzamientos y canal de prelanzamiento

Cómo Canopy versiona, etiqueta y publica imágenes de contenedores. Esta página es la referencia para los operadores que necesitan fijar versiones en producción y para los colaboradores que preparan lanzamientos.

Versionado​

Canopy sigue el Versionado Semántico. La única fuente de verdad para la versión actual es el archivo /VERSION en la raíz del repositorio.

  • Parche (por ejemplo, 1.0.0 → 1.0.1): solo correcciones de errores. Siempre es seguro actualizar.
  • Menor (por ejemplo, 1.0.0 → 1.1.0): nuevas funcionalidades. Compatible hacia atrás según la política de compatibilidad.
  • Mayor (por ejemplo, 1.x → 2.0.0): cambios incompatibles. Las notas de migración se publican con el lanzamiento.

La versión se incrementa una vez por pull request, no por commit. La entrada del CHANGELOG del PR usa la nueva versión como encabezado; el flujo de trabajo de CI version-check.yml rechaza cualquier PR que incremente VERSION sin un encabezado ## [<versión>] correspondiente en CHANGELOG.md.

Etiquetas de imágenes de contenedor​

Cada envío a main y cada etiqueta v*.*.* activa .github/workflows/docker-publish.yml, que compila y publica imágenes multi-arquitectura (amd64 + arm64) en GHCR.

Para una etiqueta de lanzamiento como v1.2.3, las etiquetas publicadas en cada imagen son:

EtiquetaApunta a¿Estable?
1.2.3exactamente ese lanzamientosí — fije esta en producción
1.2último parche en 1.2.xavanza con los parches
1última versión menor en 1.xavanza con las versiones menores
latestúltimo lanzamiento no prelanzamientoavanza con cada lanzamiento
sha-<corto>commit exactosí — depuración / prelanzamiento

Para los envíos a main (sin etiqueta), solo se producen las etiquetas main y sha-<corto> — nunca latest, nunca ninguna etiqueta semver.

Todos los manifiestos de imagen publicados están firmados con cosign OIDC sin clave. Los detalles de verificación y SBOM están en Cadena de suministro.

Canal de prelanzamiento​

Para las versiones menores que cambian la disposición de contenedores, las imágenes base, los UID predeterminados, los nombres de volumen, los puertos predeterminados o el esquema de una manera que requiere acción por parte del operador, se prepara un candidato a lanzamiento antes de la etiqueta final.

Convenciones:

  • Las etiquetas de RC son vX.Y.0-rc.N — nunca en un lanzamiento de parche, solo en versiones menores con cambios visibles para el operador.
  • La acción docker/metadata-action del flujo de publicación está configurada con flavor: latest=auto. Esto excluye automáticamente las etiquetas semver de prelanzamiento de :latest, :X.Y y :X — los RC solo se publican como :X.Y.0-rc.N. Los operadores que fijan :latest no descargarán accidentalmente un RC.
  • La Versión de GitHub para una etiqueta RC debe marcarse como prelanzamiento en la página de Versiones. El flujo de trabajo actual github-release.yml siempre crea una versión que no es prelanzamiento; el mantenedor cambia manualmente el interruptor de prelanzamiento después de que el flujo de trabajo se ejecute (o edita la versión con gh release edit vX.Y.0-rc.N --prerelease).

Período de prueba:

  • Un RC permanece disponible al menos 48–72 horas antes de la promoción, o hasta que al menos un operador externo al mantenedor informe de una actualización exitosa — lo que sea más largo.
  • Los informes de errores contra un RC se publican como vX.Y.0-rc.N+1 si el problema merece corrección. El RC anterior se deja en GHCR por reproducibilidad.

Promoción a definitivo:

  • La etiqueta final vX.Y.0 se crea en el mismo commit que el último RC. El flujo de publicación recompila y reetiqueta las imágenes multi-arquitectura; el resumen diferirá del RC aunque el código fuente sea idéntico (las entradas de compilación incluyen marcas de tiempo).
  • Las etiquetas :X.Y, :X y :latest pasan a apuntar al lanzamiento definitivo en este punto.

Preparar un lanzamiento (lista de verificación del mantenedor)​

Para un parche o versión menor normal — sin canal de RC:

  1. En una rama de funcionalidad, incremente VERSION y añada el encabezado ## [<versión>] - AAAA-MM-DD correspondiente en CHANGELOG.md.
  2. Ejecute python scripts/dump_openapi.py si alguna ruta o esquema del backend ha cambiado; confirme el resultado si ha cambiado.
  3. Abra el PR. La CI ejecuta linting, pruebas, comprobación de deriva de OpenAPI y version-check.yml.
  4. Fusione con squash en main.
  5. Desde main: git tag -s v<versión> -m "v<versión>" (o git tag v<versión> si no hay clave de firma configurada), git push origin v<versión>.
  6. El flujo de trabajo Publish GitHub Release extrae la sección ## [<versión>] de CHANGELOG.md y crea una Versión de GitHub.
  7. El flujo de trabajo Publish Docker images to GHCR compila, firma y publica las imágenes multi-arquitectura.
  8. Verifique con cosign: 
    cosign verify \
      --certificate-identity-regexp 'https://github.com/Rhizo-Tech/canopy/.+' \
      --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
      ghcr.io/rhizo-tech/canopy/backend:<versión>

Para una versión menor que requiere un RC:

  1. El mismo flujo de PR y fusión que el anterior, pero incremente a 1.Y.0-rc.1.
  2. Tras la fusión, etiquete v1.Y.0-rc.1 y envíe. El flujo de publicación compila y publica las imágenes RC (solo :1.Y.0-rc.1, nunca :latest ni etiquetas cortas — flavor: latest=auto se encarga de eso). El flujo de versión crea una Versión de GitHub; cambie manualmente a prelanzamiento después con gh release edit v1.Y.0-rc.1 --prerelease o desde la interfaz de GitHub.
  3. Espere el período de prueba. Aborde los problemas notificados con -rc.2, -rc.3 según sea necesario.
  4. Para promover: incremente VERSION a 1.Y.0 en un PR final (la entrada del CHANGELOG consolida todas las correcciones del RC), fusione, etiquete v1.Y.0, envíe. Las etiquetas :latest y las cortas apuntan ahora al lanzamiento promovido.

Fin de vida​

Solo la última línea menor recibe correcciones de seguridad. Consulte SECURITY.md para la política completa. Las líneas menores más antiguas han llegado a su fin de vida y no recibirán retroadaptaciones — los operadores con versiones antiguas deben planificar las actualizaciones siguiendo la política de compatibilidad.