Aller au contenu principal

Releases et canal de préversion

Comment Canopy gère les versions, les tags et publie les images de conteneurs. Cette page est la référence pour les opérateurs qui ont besoin d'épingler des versions en production et pour les contributeurs qui créent des releases.

Versionnage​

Canopy suit le Versionnage Sémantique. La source unique de vérité pour la version actuelle est le fichier /VERSION à la racine du dépôt.

  • Patch (par ex. 1.0.0 → 1.0.1) : corrections de bogues uniquement. Toujours sûr à mettre à niveau.
  • Minor (par ex. 1.0.0 → 1.1.0) : nouvelles fonctionnalités. Rétrocompatible selon la politique de compatibilité.
  • Major (par ex. 1.x → 2.0.0) : changements cassants. Les notes de migration sont livrées avec la release.

La version est incrémentée une fois par PR, pas par commit. L'entrée CHANGELOG du PR utilise la nouvelle version comme titre ; le workflow CI version-check.yml fait échouer tout PR qui incrémente VERSION sans avoir d'en-tête ## [<version>] correspondant dans CHANGELOG.md.

Tags d'image de conteneur​

Chaque push vers main et chaque tag v*.*.* déclenche .github/workflows/docker-publish.yml, qui construit et pousse des images multi-arch (amd64 + arm64) vers GHCR.

Pour un tag de release comme v1.2.3, les tags publiés sur chaque image sont :

TagPointe versStable ?
1.2.3exactement cette releaseoui – épinglez ce tag en production
1.2dernier patch sur 1.2.xavance sur les patches
1dernière mineure sur 1.xavance sur les mineures
latestdernière release non-préversionavance à chaque release
sha-<short>commit exactoui – débogage / préversion

Pour les pushs vers main (sans tag), seuls les tags main et sha-<short> sont produits – jamais latest, jamais de tag semver.

Tous les manifestes d'images publiés sont signés avec cosign OIDC sans clé. Les détails de vérification et de SBOM se trouvent dans Chaîne d'approvisionnement.

Canal de préversion​

Pour les versions mineures qui modifient la disposition des conteneurs, les images de base, les UIDs par défaut, les noms de volumes, les ports par défaut ou le schéma d'une manière nécessitant une action de l'opérateur, un release candidate est créé avant le tag final.

Conventions :

  • Les tags RC sont vX.Y.0-rc.N – jamais sur une release de patch, uniquement sur des mineures avec des changements visibles par les opérateurs.
  • L'action docker/metadata-action du workflow de publication est configurée avec flavor: latest=auto. Cela exclut automatiquement les tags semver de préversion de :latest, :X.Y et :X – les RC sont uniquement publiés sous :X.Y.0-rc.N. Les opérateurs qui épinglent :latest ne tireront pas accidentellement un RC.
  • La release GitHub pour un tag RC doit être marquée comme préversion sur la page des Releases. Le workflow actuel github-release.yml crée toujours une release non-préversion ; le mainteneur bascule manuellement l'option de préversion après l'exécution du workflow (ou modifie la release via gh release edit vX.Y.0-rc.N --prerelease).

Temps de maturation :

  • Un RC reste disponible pendant au moins 48 à 72 heures avant la promotion, ou jusqu'à ce qu'au moins un opérateur en dehors du mainteneur signale une mise à niveau réussie – selon ce qui est le plus long.
  • Les rapports de bogues concernant un RC sont livrés sous vX.Y.0-rc.N+1 si le problème mérite une correction. L'ancien RC est conservé dans GHCR pour la reproductibilité.

Promotion vers la version finale :

  • Le tag final vX.Y.0 est créé sur le même commit que le dernier RC. Le workflow de publication reconstruit et retague les images multi-arch ; le digest différera du RC même si la source est identique (les entrées de build incluent des horodatages).
  • Les tags :X.Y, :X et :latest pointent désormais vers la release finale.

Créer une release (liste de contrôle du mainteneur)​

Pour un patch ou une mineure normale – pas besoin du canal RC :

  1. Sur une branche de fonctionnalité, incrémenter VERSION et ajouter l'en-tête ## [<version>] - YYYY-MM-DD correspondant dans CHANGELOG.md.
  2. Exécuter python scripts/dump_openapi.py si une route backend ou un schéma a changé ; commiter le résultat s'il a changé.
  3. Ouvrir le PR. CI exécute lint, tests, vérification de dérive OpenAPI et version-check.yml.
  4. Squash-merger vers main.
  5. Depuis main : git tag -s v<version> -m "v<version>" (ou git tag v<version> si aucune clé de signature n'est configurée), git push origin v<version>.
  6. Le workflow Publish GitHub Release extrait la section ## [<version>] de CHANGELOG.md et crée une release GitHub.
  7. Le workflow Publish Docker images to GHCR construit, signe et publie les images multi-arch.
  8. Vérifier avec 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:<version>

Pour une mineure nécessitant un RC :

  1. Même flux PR-et-merge qu'au-dessus, mais incrémenter vers 1.Y.0-rc.1.
  2. Après le merge, tagger v1.Y.0-rc.1 et pousser. Le workflow de publication construit et pousse les images RC (uniquement :1.Y.0-rc.1, jamais :latest ni les tags courts – flavor: latest=auto s'en charge). Le workflow de release crée une release GitHub ; basculer manuellement en préversion ensuite via gh release edit v1.Y.0-rc.1 --prerelease ou dans l'interface GitHub.
  3. Attendre la fenêtre de maturation. Traiter les problèmes signalés avec -rc.2, -rc.3 au besoin.
  4. Pour promouvoir : incrémenter VERSION vers 1.Y.0 dans un PR final (l'entrée CHANGELOG consolide tous les correctifs RC), merger, tagger v1.Y.0, pousser. Les tags :latest et les tags courts pointent maintenant vers la release promue.

Fin de vie​

Seule la dernière ligne mineure reçoit des corrections de sécurité. Voir SECURITY.md pour la politique complète. Les lignes mineures plus anciennes sont en fin de vie et ne recevront pas de rétroportages – les opérateurs sur des versions plus anciennes doivent planifier des mises à niveau conformément à la politique de compatibilité.