docs/processo.md descrive il percorso di una modifica come in un'azienda: rami, commit, richieste di unione, controlli richiesti e protezione di main da configurare su Gitea, che cosa garantisce ciascun lavoro della CI, etichette del registro (:main, :sha-, :X.Y.Z, :latest), pulizia, rilievi di sicurezza, rilasci e correzioni urgenti, e che cosa solo la prima esecuzione vera può provare. CLAUDE.md e la guida per lo sviluppo dicevano che la verifica girava a ogni push, e non era vero: ora descrivono la CI com'è. docs/docker.md dice quali etichette ha l'immagine e come risalire all'esecuzione che l'ha costruita. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
199 lines
14 KiB
Markdown
199 lines
14 KiB
Markdown
# Processo: dal ramo al rilascio
|
|
|
|
Come una modifica arriva in `main` e da lì a una versione, con le stesse garanzie di un'azienda che non accetta codice
|
|
non verificato. Vale per Alberto e per chiunque lavori al repository, persone o agenti. Repository: il Gitea di casa,
|
|
<https://gitea.encke-hake.ts.net/Alby96/Febe> (non GitHub: niente strumenti di GitHub). Il motivo di ogni scelta è in
|
|
`docs/decisioni.md`, alle righe del 20 ottobre 2026.
|
|
|
|
## In breve
|
|
|
|
1. Un ramo per filone di lavoro, nato da `main`.
|
|
2. Commit piccoli e separati, ciascuno con un messaggio che dice che cosa cambia e perché.
|
|
3. A ogni push la verifica parte da sola: controlli, prove, installatore, immagine.
|
|
4. Una richiesta di unione per ramo, con il modello compilato, e una revisione.
|
|
5. Si unisce in `main` solo con la verifica verde sull'ultimo commit (protezione di `main`), con un commit di unione;
|
|
il ramo si cancella.
|
|
6. Dopo l'unione la verifica gira su `main` e pubblica l'immagine `:main` e `:sha-<commit>`.
|
|
7. Un rilascio è un tag `vX.Y.Z` su `main`.
|
|
|
|
## Rami
|
|
|
|
- Nome: `<tipo>/<argomento>`, in minuscolo, parole separate da trattini, in italiano. Tipi:
|
|
|
|
| Tipo | Per |
|
|
|---|---|
|
|
| `funzione/` | una funzione nuova (`funzione/esporta-csv`) |
|
|
| `correzione/` | un difetto (`correzione/webview2-avvio`) |
|
|
| `urgente/` | una correzione da rilasciare subito (vedi «Correzioni urgenti») |
|
|
| `ci/` | flussi, script e immagini della CI (`ci/pipeline-aziendale`) |
|
|
| `strumenti/` | strumenti di sviluppo (`strumenti/vscode`) |
|
|
| `documenti/` | solo documenti e guida |
|
|
| `rilascio/` | la preparazione di una versione (`rilascio/0.2.0`) |
|
|
|
|
- Si parte da `main` aggiornato e si resta brevi: giorni, non settimane. Se `main` va avanti, il ramo si aggiorna
|
|
(pulsante «Aggiorna il ramo» della richiesta di unione, o `git merge origin/main`) prima di unire.
|
|
- Su `main` non si fa push diretto: ci si arriva solo da una richiesta di unione.
|
|
|
|
## Commit
|
|
|
|
- Piccoli e logici: ogni commit compila e passa le prove da solo (così `git bisect` funziona).
|
|
- Messaggio in italiano: la prima riga (al massimo 72 caratteri) dice che cosa cambia; il corpo, dopo una riga vuota,
|
|
dice perché. Non un elenco di file.
|
|
- I commit scritti con un agente finiscono con una riga vuota e `Co-Authored-By: …` dell'agente.
|
|
- Mai nel repository: risultati di compilazione (`bin/`, `obj/`, `out/`), segreti, campioni grezzi della sonda, dati
|
|
di Alberto.
|
|
|
|
## Richieste di unione
|
|
|
|
- Una per ramo, con il modello (`.gitea/pull_request_template.md`): sintesi, perché, che cosa cambia, come è stato
|
|
provato (comandi e risultati, e che cosa non è stato provato), rischi e ritorno indietro, le quattordici regole di
|
|
§2 della specifica. Le righe per `CHANGELOG.md` e `docs/stato.md` stanno nella richiesta: le aggiunge chi integra.
|
|
- Revisione: Alberto è il proprietario di tutto (`.gitea/CODEOWNERS`). Le osservazioni si risolvono con commit nuovi
|
|
sullo stesso ramo, non riscrivendo quelli già rivisti.
|
|
- Stile di unione: **commit di unione** («Crea un commit di unione»), con il titolo della richiesta; poi il ramo si
|
|
cancella («Elimina il ramo dopo l'unione», da tenere attivo nelle impostazioni del repository).
|
|
- Tornare indietro: `git revert -m 1 <commit di unione>` in una nuova richiesta di unione.
|
|
|
|
## Controlli richiesti e protezione di main
|
|
|
|
I controlli richiesti sono i quattro lavori della verifica, come Gitea li riporta sul commit:
|
|
`verifica / controlli (push)`, `verifica / prove (push)`, `verifica / installatore (push)`,
|
|
`verifica / immagine (push)`. Una richiesta di unione mostra lo stato del suo ultimo commit, che il push del ramo ha
|
|
già verificato: per questo la verifica non gira anche su `pull_request`.
|
|
|
|
Regola di protezione di `main` (Impostazioni ▸ Rami ▸ Aggiungi regola; la imposta chi integra, una volta che i
|
|
quattro controlli sono comparsi almeno una volta):
|
|
|
|
| Impostazione | Valore |
|
|
|---|---|
|
|
| Schema del ramo | `main` |
|
|
| Push | disattivato: solo da richiesta di unione |
|
|
| Push forzato | disattivato |
|
|
| Controllo di stato | attivo, con gli schemi `verifica / controlli (push)`, `verifica / prove (push)`, `verifica / installatore (push)`, `verifica / immagine (push)` |
|
|
| Blocca l'unione se la richiesta è indietro rispetto al ramo di base | attivo: con il ramo aggiornato il commit di unione ha lo stesso contenuto del commit verificato |
|
|
| Approvazioni richieste | 1 se le richieste le apre un account diverso da quello di Alberto; 0 se le apre lui (Gitea non conta l'approvazione dell'autore) |
|
|
| Annulla le approvazioni superate da nuovi commit | attivo |
|
|
| Blocca l'unione con revisioni che chiedono modifiche | attivo |
|
|
| Anche gli amministratori seguono la regola | attivo |
|
|
|
|
E nei tag protetti (Impostazioni ▸ Tag): `v*` creabili solo da Alberto.
|
|
|
|
## La CI
|
|
|
|
Gitea Actions su un solo act_runner (etichetta `ubuntu-latest`, un lavoro alla volta). I lavori parlano con il demone
|
|
Docker del server, lo stesso che costruisce Encelado, Mimante e gli altri progetti di Alberto. I flussi stanno in
|
|
`.gitea/workflows/`, il codice comune in `.gitea/scripts/` (si lancia anche a mano).
|
|
|
|
| Lavoro | Quando | Che cosa garantisce |
|
|
|---|---|---|
|
|
| `controlli` | ogni push | sintassi di tutti gli script di shell (`bash -n`, `sh -n`) e righe Unix; flussi senza tabulazioni; nessun segno di conflitto; versione in `Directory.Build.props` valida; ogni progetto di `Febe.slnx` esiste; ogni JSON si legge; nessun segreto in tutta la storia (gitleaks 8.30.1, `--redact`) |
|
|
| `prove` | dopo `controlli` | in un contenitore Debian 13 (`node:24-trixie`) con Chromium della distribuzione, Xvfb, ffmpeg, NSIS, Node e la lingua italiana: tutta la soluzione compila con gli avvisi come errori e **tutte** le prove di `tests/Febe.Tests` passano senza saltarsi; quelle della categoria `SitoDiProva` passano anche con il seme dell'esecuzione. Risultati `.trx` fra gli artefatti (14 giorni) |
|
|
| `installatore` | dopo `prove` | `Febe.exe` in un file solo, `Febe-Setup-<versione>-ci.<numero>.exe` e lo zip portabile si costruiscono, ciascuno sotto i 100 MB; artefatti per 14 giorni |
|
|
| `immagine` | dopo `prove` | l'immagine si costruisce con buildx (dentro girano compilazione e prove), il contenitore parte **senza rete** come dice la guida e diventa «healthy», Chromium e la lingua italiana ci sono, si ferma entro 30 secondi; Trivy 0.75.0 non trova vulnerabilità CRITICAL con correzione disponibile. Solo dopo un push su `main`: pubblicazione `:main` e `:sha-<commit>` |
|
|
|
|
La verifica gira a ogni push su qualunque ramo e a mano (Actions ▸ verifica ▸ Esegui, con un seme facoltativo). Su un
|
|
ramo un push nuovo annulla l'esecuzione in corso; su `main` ogni unione arriva fino in fondo.
|
|
|
|
Altri flussi: `rilascio.yml` a ogni tag (vedi «Rilasci») e `pulizia.yml` ogni lunedì (vedi «Pulizia»).
|
|
|
|
### Il mondo sintetico e il suo seme
|
|
|
|
Le prove non contattano mai Instagram: usano il sito di prova (`tools/Febe.SitoDiProva`), con dati sintetici generati
|
|
da un seme. Nella CI le prove girano con il seme 13 e quelle della categoria `SitoDiProva` di nuovo con il seme
|
|
`1000 + numero dell'esecuzione`, scritto nel registro del passo «Semi del mondo sintetico». Per rifare un errore, in
|
|
locale o dalla CI a mano con quel seme:
|
|
|
|
```sh
|
|
FEBE_SEME_PROVA=<seme> dotnet test tests/Febe.Tests --filter "TestCategory=SitoDiProva"
|
|
```
|
|
|
|
### Segreti e variabili
|
|
|
|
- `REGISTRY_TOKEN` (segreto del repository): token di Alberto con «package: read and write». Senza, `verifica` e
|
|
`rilascio` costruiscono, provano e scansionano l'immagine ma non la pubblicano, con un avviso, e restano verdi.
|
|
- `REGISTRY` (variabile, facoltativa): il registro come lo raggiunge il runner (`192.168.30.23:3000`); se manca si usa
|
|
l'host dell'indirizzo del server Gitea.
|
|
- Le credenziali vanno nella configurazione del client Docker del lavoro, mai nel demone, e si tolgono alla fine.
|
|
Nessun flusso stampa segreti; `PipelineTests` lo controlla a ogni esecuzione.
|
|
- I segreti sono leggibili da qualunque flusso di questo repository, su qualunque ramo: chi può fare push può leggerli.
|
|
Per questo il permesso di scrittura sul repository resta ad Alberto e agli account di cui si fida.
|
|
|
|
## Registro dei container: le etichette
|
|
|
|
Sul registro di Gitea, `192.168.30.23:3000/alby96/febe`:
|
|
|
|
| Etichetta | Chi la crea | Quando cambia | Per che cosa |
|
|
|---|---|---|---|
|
|
| `:latest` | `rilascio`, solo versioni senza trattino | a ogni rilascio stabile | Unraid e Docker Compose |
|
|
| `:X.Y.Z` | `rilascio` (anche `X.Y.Z-rc.1` per un'anteprima) | mai | una versione precisa, per tornare indietro |
|
|
| `:main` | `verifica`, dopo ogni unione in `main` | a ogni unione (mai all'indietro) | provare `main` su un server di prova; non per l'archivio vero |
|
|
| `:sha-<7 caratteri>` | `verifica`, dopo ogni unione in `main` | mai | un commit preciso di `main` |
|
|
|
|
Ogni immagine della CI porta le etichette Docker `febe.ci.workflow`, `febe.ci.run`, `febe.ci.ref` e `febe.ci.commit`,
|
|
oltre a quelle OCI del Dockerfile: da un'immagine si risale all'esecuzione e al commit. Le `:sha-` si accumulano: una
|
|
regola di pulizia dei pacchetti (Impostazioni ▸ Pacchetti ▸ Regole di pulizia) può tenere sempre `latest`, `main` e
|
|
le versioni e togliere le `sha-.*` più vecchie di 30 giorni.
|
|
|
|
## Pulizia
|
|
|
|
Il demone Docker è condiviso con gli altri progetti: la CI di Febe toglie solo ciò che porta i suoi segni (etichetta
|
|
`febe.ci.run`, repository locale `febe-ci`, builder `febe-ci-<esecuzione>`), più le immagini senza nome più vecchie di
|
|
72 ore (`.gitea/scripts/pulizia-docker.sh`).
|
|
|
|
| Quando | Che cosa si toglie |
|
|
|---|---|
|
|
| alla fine di ogni lavoro «immagine», sempre | il contenitore di prova con i suoi volumi anonimi, l'immagine provata, il builder buildx dell'esecuzione con la sua cache, l'archivio dell'immagine, le credenziali del registro |
|
|
| all'inizio di ogni lavoro «immagine» | i resti di esecuzioni interrotte più vecchi di 90 minuti (un lavoro dura al massimo 60 minuti) e di un tentativo precedente della stessa esecuzione |
|
|
| ogni lunedì e a mano (`pulizia.yml`) | gli stessi resti, l'immagine `febe:ci` del vecchio flusso se nessuno la usa, le immagini senza nome più vecchie di 72 ore |
|
|
| mai | immagini, contenitori e volumi degli altri progetti; la cache di costruzione del demone; i volumi con un nome; le immagini col nome del registro |
|
|
|
|
## Rilievi di sicurezza
|
|
|
|
- **gitleaks** (lavoro `controlli`). Un segreto vero si **revoca subito** (gettone di Telegram da BotFather, token di
|
|
Gitea dalle impostazioni dell'utente) e se ne crea uno nuovo: toglierlo dalla storia non basta, perché qualcuno può
|
|
averlo già. Solo dopo, se serve, si riscrive la storia, d'accordo con Alberto. Un falso allarme (un dato di prova
|
|
finto, già controllato) si toglie aggiungendo la sua impronta («Fingerprint», nel registro del lavoro o nel
|
|
rapporto `rapporto-gitleaks`) a `.gitleaksignore`, con un commento sulla riga sopra: che cos'è, chi l'ha
|
|
controllato, quando. Mai disattivare una regola.
|
|
- **Trivy** (lavoro `immagine`, anche nel rilascio). Una vulnerabilità CRITICAL con correzione disponibile ferma il
|
|
lavoro e l'immagine non si pubblica. Che cosa fare: per un pacchetto di Debian di solito basta rilanciare (il
|
|
Dockerfile applica gli aggiornamenti della distribuzione); per una dipendenza .NET si aggiorna la sua versione in
|
|
`Directory.Packages.props` (una dipendenza nuova va chiesta ad Alberto); per il runtime .NET si ricostruisce con
|
|
l'SDK aggiornato. Le HIGH, e le CRITICAL ancora senza correzione, non fermano nulla ma si guardano nel rapporto
|
|
`sicurezza-immagine` (`trivy.json`) e, se riguardano ciò che Febe usa, diventano una segnalazione. Un'eccezione si
|
|
scrive solo in `.trivyignore`, alla radice: l'identificativo con una scadenza (`CVE-AAAA-NNNN exp:AAAA-MM-GG`, al
|
|
massimo 90 giorni) e, sulla riga sopra, il motivo e chi l'ha deciso.
|
|
- Strumenti: gitleaks e Trivy sono gli unici strumenti esterni della CI, approvati da Alberto, e girano solo nella
|
|
CI. Si aggiornano cambiando versione e impronta SHA-256 in `.gitea/scripts/strumento.sh`, in una richiesta di
|
|
unione con una riga in `docs/decisioni.md`, preferendo versioni uscite da almeno due settimane.
|
|
|
|
## Rilasci
|
|
|
|
1. In un ramo `rilascio/X.Y.Z`: `<Version>` in `Directory.Build.props`, la sezione `## X.Y.Z` di `CHANGELOG.md` (è il
|
|
testo delle note della release), `docs/stato.md`. Richiesta di unione, verifica verde, unione.
|
|
2. Sul commit di unione in `main`: `git tag -a vX.Y.Z -m "Febe X.Y.Z"` e `git push origin vX.Y.Z`.
|
|
3. `rilascio.yml` controlla che il tag coincida con `<Version>`, rifà le prove, costruisce installatore e zip,
|
|
costruisce, prova e scansiona l'immagine, la pubblica come `:X.Y.Z` (e `:latest` se la versione non ha trattini) e
|
|
crea la release con installatore, zip, modello di Unraid e archivio per Compose.
|
|
4. Un'anteprima è `vX.Y.Z-rc.N`: stessa strada, `:latest` non si sposta e la release è segnata come anteprima (come
|
|
ogni versione `0.x`).
|
|
5. Se manca `REGISTRY_TOKEN` la release esce senza immagine e lo dice; aggiunto il segreto, si rilancia il flusso del
|
|
tag e le note si correggono.
|
|
|
|
## Correzioni urgenti
|
|
|
|
- Se `main` contiene solo ciò che si vuole rilasciare: ramo `urgente/<argomento>` da `main`, richiesta di unione con la
|
|
verifica verde come sempre (nessuna scorciatoia), poi un rilascio di correzione (`X.Y.Z+1`) come sopra.
|
|
- Se `main` contiene già lavoro da non rilasciare: ramo `rilascio/X.Y` dal tag della versione in uso, la correzione con
|
|
`git cherry-pick` (o scritta lì), `<Version>` a `X.Y.Z+1`, tag `vX.Y.Z+1` su quel ramo (il rilascio parte da
|
|
qualunque tag); poi la stessa correzione entra in `main` con la sua richiesta di unione.
|
|
|
|
## Che cosa solo la prima esecuzione vera può provare
|
|
|
|
Qui non ci sono runner né demone Docker: i flussi sono stati controllati come testo (struttura, espressioni, `bash -n`
|
|
di ogni blocco `run`), gli script con un client Docker finto. Restano da vedere alla prima esecuzione: il contenitore
|
|
`node:24-trixie` con le azioni dentro; le prove con il browser nel contenitore (nessuna saltata); `upload-artifact@v3`
|
|
con `retention-days`; la concorrenza; il builder buildx con il nome dell'esecuzione; la prova del contenitore senza
|
|
rete fino a «healthy»; il download e la scansione di Trivy (e se trova CRITICAL da correggere); gitleaks sulla storia;
|
|
la pubblicazione su `main` con il segreto; la pulizia settimanale sul demone vero.
|