Passa al contenuto principale

Rilasci e canale di pre-rilascio

Come Canopy versiona, etichetta e pubblica le immagini dei contenitori. Questa pagina è il riferimento per gli operatori che devono fissare le versioni in produzione e per i collaboratori che preparano i rilasci.

Versioning​

Canopy segue il Versionamento Semantico. L'unica fonte di verità per la versione corrente è il file /VERSION nella radice del repository.

  • Patch (ad es. 1.0.0 → 1.0.1): solo correzioni di bug. Sempre sicuro da aggiornare.
  • Minore (ad es. 1.0.0 → 1.1.0): nuove funzionalità. Compatibile con le versioni precedenti secondo la politica di compatibilità.
  • Maggiore (ad es. 1.x → 2.0.0): modifiche incompatibili. Le note di migrazione vengono distribuite con il rilascio.

La versione viene incrementata una volta per pull request, non per commit. La voce del CHANGELOG del PR utilizza la nuova versione come intestazione; il flusso di lavoro CI version-check.yml fa fallire qualsiasi PR che incrementi VERSION senza un'intestazione ## [<versione>] corrispondente in CHANGELOG.md.

Tag delle immagini contenitore​

Ogni push su main e ogni tag v*.*.* attiva .github/workflows/docker-publish.yml, che compila e pubblica immagini multi-architettura (amd64 + arm64) su GHCR.

Per un tag di rilascio come v1.2.3, i tag pubblicati su ciascuna immagine sono:

TagPunta aStabile?
1.2.3esattamente quel rilasciosì — fissare questo in produzione
1.2ultima patch su 1.2.xsi aggiorna con le patch
1ultima versione minore su 1.xsi aggiorna con le versioni minori
latestultimo rilascio non pre-rilasciosi aggiorna con ogni rilascio
sha-<breve>commit esattosì — debug / pre-rilascio

Per i push su main (senza tag), vengono prodotti solo i tag main e sha-<breve> — mai latest, mai alcun tag semver.

Tutti i manifest delle immagini pubblicate sono firmati con cosign OIDC senza chiave. I dettagli di verifica e SBOM si trovano in Catena di fornitura.

Canale di pre-rilascio​

Per le versioni minori che modificano il layout dei contenitori, le immagini base, gli UID predefiniti, i nomi dei volumi, le porte predefinite o lo schema in un modo che richiede azioni da parte dell'operatore, viene preparato un candidato al rilascio prima del tag finale.

Convenzioni:

  • I tag RC sono vX.Y.0-rc.N — mai su un rilascio di patch, solo su versioni minori con modifiche visibili all'operatore.
  • L'azione docker/metadata-action del flusso di pubblicazione è configurata con flavor: latest=auto. Questo esclude automaticamente i tag semver di pre-rilascio da :latest, :X.Y e :X — gli RC vengono pubblicati solo come :X.Y.0-rc.N. Gli operatori che fissano :latest non scaricheranno accidentalmente un RC.
  • Il Rilascio GitHub per un tag RC dovrebbe essere contrassegnato come pre-rilascio nella pagina dei Rilasci. Il flusso di lavoro github-release.yml attuale crea sempre un rilascio non in pre-rilascio; il manutentore passa manualmente il toggle di pre-rilascio dopo l'esecuzione del flusso di lavoro (o modifica il rilascio tramite gh release edit vX.Y.0-rc.N --prerelease).

Periodo di maturazione:

  • Un RC rimane disponibile per almeno 48–72 ore prima della promozione, o fino a quando almeno un operatore esterno al manutentore riporta un aggiornamento riuscito — a seconda di quale sia più lungo.
  • Le segnalazioni di bug contro un RC vengono pubblicate come vX.Y.0-rc.N+1 se il problema merita una correzione. Il RC precedente viene lasciato in GHCR per la riproducibilità.

Promozione a definitivo:

  • Il tag finale vX.Y.0 viene creato sullo stesso commit dell'ultimo RC. Il flusso di pubblicazione ricompila e ri-etichetta le immagini multi-architettura; il digest differirà dall'RC anche se il codice sorgente è identico (gli input di compilazione includono timestamp).
  • I tag :X.Y, :X e :latest passano a puntare al rilascio definitivo in questo momento.

Preparare un rilascio (lista di controllo del manutentore)​

Per una patch o una versione minore normale — senza canale RC:

  1. Su un branch di funzionalità, incrementare VERSION e aggiungere l'intestazione ## [<versione>] - AAAA-MM-GG corrispondente in CHANGELOG.md.
  2. Eseguire python scripts/dump_openapi.py se qualche rotta o schema del backend è cambiato; committare il risultato se è cambiato.
  3. Aprire il PR. La CI esegue linting, test, verifica della deriva OpenAPI e version-check.yml.
  4. Eseguire il merge con squash su main.
  5. Da main: git tag -s v<versione> -m "v<versione>" (o git tag v<versione> se non è configurata alcuna chiave di firma), git push origin v<versione>.
  6. Il flusso di lavoro Publish GitHub Release estrae la sezione ## [<versione>] da CHANGELOG.md e crea un Rilascio GitHub.
  7. Il flusso di lavoro Publish Docker images to GHCR compila, firma e pubblica le immagini multi-architettura.
  8. Verificare 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:<versione>

Per una versione minore che richiede un RC:

  1. Lo stesso flusso PR-e-merge di cui sopra, ma incrementare a 1.Y.0-rc.1.
  2. Dopo il merge, etichettare v1.Y.0-rc.1 e fare il push. Il flusso di pubblicazione compila e pubblica le immagini RC (solo :1.Y.0-rc.1, mai :latest o tag brevi — flavor: latest=auto gestisce questo). Il flusso di rilascio crea un Rilascio GitHub; passare manualmente a pre-rilascio in seguito tramite gh release edit v1.Y.0-rc.1 --prerelease o dall'interfaccia GitHub.
  3. Attendere il periodo di maturazione. Gestire eventuali problemi segnalati con -rc.2, -rc.3 secondo necessità.
  4. Per promuovere: incrementare VERSION a 1.Y.0 in un PR finale (la voce del CHANGELOG consolida tutte le correzioni RC), eseguire il merge, etichettare v1.Y.0, fare il push. I tag :latest e brevi puntano ora al rilascio promosso.

Fine vita​

Solo l'ultima linea minore riceve correzioni di sicurezza. Vedere SECURITY.md per la politica completa. Le linee minori più vecchie sono a fine vita e non riceveranno backport — gli operatori su versioni più vecchie dovrebbero pianificare gli aggiornamenti seguendo la politica di compatibilità.