​

Processo di release

Questa pagina descrive il flusso di release attuale del repository, non una pipeline idealizzata per uno stato futuro.

​

Modello di shipping attuale

• Le pull request sono l’unità di consegna.
• GitHub Actions è la fonte di verità per i controlli del repository.
• apps/web, apps/app e apps/api vengono distribuite tramite Vercel nell’attuale postura alpha.
• apps/worker viene distribuita tramite un deployment in stile Railway.
• I tag semver vengono utilizzati per le release deliberate.
• Il buildVersion a runtime è distinto dalla versione di release semver.

​

Controlli predefiniti attuali

Il repository valida:

• lint
• lint della documentazione
• igiene della documentazione
• deriva della specifica OpenAPI
• igiene delle release
• build della documentazione
• typecheck
• test
• build

Esistono ulteriori workflow di hardening come la dependency review e CodeQL, ma possono dipendere dal piano/configurazione del repository.

​

Politica dei treni di release

Fino all’alpha, Switchbord utilizza il semver a treni di release:

• patch per correzioni, correzioni alla documentazione e igiene delle release
• minor per ondate coerenti di funzionalità
• major solo per la semantica stabile 1.0.0

Non creare una versione minor per ogni PR. Una versione dovrebbe descrivere uno stato coerente del repository.

​

Passaggi di release obbligatori

Per ogni release deliberata:

1. Aggiornare package.json alla versione prevista.
2. Aggiornare CHANGELOG.md con ## vX.Y.Z e date fattuali basate su git.
3. Aggiornare il changelog web pubblico in MDX se la release è rivolta ai clienti.
4. Aggiornare la documentazione Mintlify per qualsiasi funzionalità visibile all’utente o cambiamento del comportamento operativo.
5. Eseguire:
   pnpm release:hygiene
   pnpm lint
   pnpm --filter docs docs:hygiene
   pnpm typecheck
   pnpm test
   pnpm build
   
6. Effettuare il merge della PR di release.
7. Taggare esattamente la stessa versione:
   pnpm release:tag
   pnpm release:tag:push
   
8. Confermare che la GitHub Release sia stata creata per il tag corrispondente.

​

Retro-datazione dei tag storici

Le versioni alpha storiche precedenti a questa politica non sono state taggate in modo coerente. Non creare tag fittizi. Se è necessaria una retro-datazione prima dell’alpha:

1. Identificare il commit esatto che rappresentava quello stato di release.
2. Verificare package.json e CHANGELOG.md in quel commit.
3. Creare il tag storico solo se l’evidenza è inequivocabile.
4. Preferire l’inizio della corrispondenza rigorosa al prossimo treno di release se il confine storico non è chiaro.

​

Linee guida per i contributori

• Non assumere che una funzionalità sia pronta per la release solo perché compila in locale.
• Se la tua modifica altera il comportamento a runtime, aggiorna sia la documentazione Mintlify sia la documentazione operativa a livello di repository che descrive lo stesso contratto.
• Se la tua modifica influisce sullo stato di marketing pubblico, aggiorna il changelog web o spiega esplicitamente il perché non lo fai nel corpo della PR.
• Se una data del changelog non è supportata da git log o gh pr view, non commetterla.
• Se una modifica richiederebbe nuovi gate di CI, documentalo come un follow-up esplicito invece di far intendere che esista già.

​

Hardening pianificato

Queste sono aggiunte previste, ma dovrebbero essere descritte come pianificate finché non sono attive in CI:

• build in container per i runtime a esecuzione prolungata
• validazione delle migrazioni
• controlli ambientali più rigorosi
• politica di promozione dell’ambiente di release

​

Prosegui la lettura

• Versionamento
• CI/CD
• Flusso di contribuzione