Vai al contenuto

Versioni e rilasci

Il numero di versione dice se un aggiornamento può rompere la tua applicazione, il changelog dice cosa fare per rimediare. Questa pagina scrive le due promesse e come si fa davvero un rilascio.

Cosa promette un numero di versione

Griglia segue il versionamento semantico. È ancora su 0.x, dove le regole scalano di una posizione:

Parte di 0.MINOR.PATCH Cambia per Può romperti?
MINOR funzioni, e tutto ciò che tocca la superficie pubblica sì — leggi il changelog prima di alzarla
PATCH correzioni, documentazione, dettagli interni no

Fissa quindi la minor che hai provato ("alle80/griglia": "^0.89.0") e tratta un salto di minor come un piccolo progetto di aggiornamento: la procedura è il runbook di aggiornamento.

Non c'è una data per la 1.0: arriverà quando la superficie pubblica qui sotto smetterà di muoversi, non a calendario.

Che cosa è pubblico

Cambiare una di queste cose è una rottura, e finisce in una minor:

  • Chiavi di configurazione di config/griglia.php e impostazioni dei gruppi agent, app e optimization — vedi File di configurazione e Impostazioni.
  • Comandi artisan: nome, argomenti e opzioni — vedi Comandi artisan.
  • File pubblicabili: viste, file di lingua, script e asset precompilati, e i tag che li pubblicano.
  • Punti di estensione: il gate di accesso, il modello utente, Mode, le rotte registrate e i loro nomi.
  • L'evento TodoChanged e il suo payload — vedi Eventi e broadcasting.
  • Tabelle e colonne che l'applicazione ospite può leggere.

Tutto il resto — classi senza una pagina di documentazione, helper interni, dettagli del CSS, la forma di un partial Blade — è interno e può cambiare in una patch. Se dipendi da qualcosa di interno, scrivilo in una issue: un punto di estensione costa meno, a entrambi, di un fork privato.

Le deprecazioni si annunciano sotto Deprecated nel changelog e, quando la modifica lo permette, continuano a funzionare per un'altra minor prima di sparire.

Versioni supportate

È supportata solo la minor più recente: le correzioni si mettono lì, non ci sono backport sulle 0.x precedenti. Il perché sta in Governance.

Il changelog è il rilascio

Ogni rilascio è descritto una volta sola, in CHANGELOG.md, nel formato Keep a Changelog. Nessuno lo riscrive: la GitHub Release è generata da quella sezione da .github/workflows/release.yml, così un rilascio non può finire raccontato in due modi diversi.

Anche le definizioni dei link che chiudono il file sono generate:

php .github/scripts/changelog-notes.php --links           # stampa tutto il blocco [x.y.z]: …/compare/…
php .github/scripts/changelog-notes.php --links --write   # lo riscrive in fondo al changelog
php .github/scripts/changelog-notes.php 0.89.12           # le note di una versione, come vengono pubblicate

ReleaseProcessTest fallisce se il blocco non corrisponde più, quindi non può marcire in silenzio.

Come si fa un rilascio

Quattro passi a mano, poi prosegue GitHub.

# 1. Sposta le voci di Unreleased sotto un titolo loro, con la data di oggi.
#    ## [0.90.0] - 2026-08-23
php .github/scripts/changelog-notes.php --links --write   # 2. rigenera il blocco di link in fondo al file

npm run build                                             # 3. solo se sono cambiati CSS, JS o viste
composer qa                                               # 4. stile, suite, pagine di reference generate

git tag v0.90.0 && git push origin master v0.90.0

Il push del tag fa partire tutto il resto:

Poi Chi
la versione compare su Packagist l'hook di Packagist sul repository
esce una GitHub Release con le note del changelog e il link di confronto release.yml
il sito della documentazione viene ricostruito docs.yml

Un tag la cui versione non ha una sezione nel changelog fa fallire il workflow di rilascio invece di pubblicare una release vuota. Per ripubblicare le note di un tag già uscito, lancia a mano il workflow release indicando quel tag.

Dove sta il sorgente

alle80/griglia è un mirror di pubblicazione. Il package si sviluppa dentro il monorepo dell'applicazione che lo usa, in src/packages/griglia, e uno script di rilascio ricopia quella cartella su master, la tagga e fa push. Lo script si rifiuta di partire se master ha versioni o file che il sorgente non ha, così un rilascio non può cancellare in silenzio del lavoro arrivato da un'altra parte.

Per chi contribuisce non cambia niente: si parte da master, la pull request si apre lì e lì viene rivista e integrata. Quello che aggiunge è un passo per chi mantiene — riportare l'integrazione nel monorepo prima del rilascio successivo — ed è il motivo per cui su master si vedono tag e merge invece di una lunga storia quotidiana.

Metadati del repository

Descrizione, homepage, topic, gli interruttori delle funzioni e la segnalazione privata delle vulnerabilità non stanno nel codice, quindi invecchiano senza che nessuno se ne accorga. Stanno in .github/repository.json, e li applica uno script:

php .github/scripts/repo-metadata.php          # che cosa è diverso dal repository vero
php .github/scripts/repo-metadata.php --apply  # scrive il file su GitHub, serve `gh auth login`

La descrizione lì e quella di composer.json sono la stessa frase, perché GitHub e Packagist sono i due posti che uno sconosciuto legge per primi; se divergono un test fallisce.

L'immagine sociale è l'eccezione: GitHub non ha un'API per caricarla. Dopo aver cambiato docs/images/social-preview.png (PNG 1280×640) caricala a mano da Settings → General → Social preview. La stessa immagine è l'og:image di ogni pagina di questo sito, tramite overrides/main.html.

Vedi anche

Griglia v0.95.0