Mantieni questo manuale

La sorgente vive nel repository dell'applicazione, così una modifica di comportamento e la sua documentazione possono arrivare insieme. Gli screenshot generati vengono pubblicati in un bucket Cloudflare R2 sotto un prefisso versionato per ogni versione del manuale e non vengono mai committati nell'albero dell'applicazione.

Modifica la prosa

1. Modifica o aggiungi il file MDX inglese sotto docs-site/docs.
2. Aggiorna il file corrispondente per ogni locale pubblicato sotto docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
3. Aggiungi una nuova pagina a docs-site/sidebars.ts.
4. Aggiorna docs-site/metadata/features.json quando la copertura cambia.
5. Aggiorna le voci corrispondenti in docs-site/metadata/surface-inventory.json. Una superficie diventa verified solo quando la sua UI di produzione attuale, la prosa e la copertura degli screenshot sono state tutte riviste.
6. Esegui make manual_check.
7. Rivedi la build di produzione in locale con make manual_serve, incluso il selettore di lingua e ogni percorso localizzato.

La validazione richiede che ogni albero di traduzione pubblicato contenga gli stessi percorsi di pagina dell'albero sorgente inglese. Rifiuta inoltre i corpi di pagina tradotti identici all'inglese, così le pagine nuove non possono uscire di nascosto come copie non tradotte. Gli URL pubblici inglesi restano invariati; le altre lingue vengono pubblicate sotto il proprio prefisso di locale versionato.

Mantieni autorevole l'inventario di copertura

L'inventario definisce il perimetro V1 del manuale inglese: ogni pagina Beamer, ogni foglia o editor di Impostazioni V2 e ogni flusso di lavoro principale che crea o modifica in modo sostanziale dati o configurazione trasversale. Ogni voce registra il file sorgente che la possiede e un'ancora nel testo sorgente. La validazione fallisce se uno dei due scompare: così un cambio di route o di UI è costretto ad aggiornare l'audit del manuale invece di lasciare in giro una riga stantia e invisibile.

Gli stati di copertura hanno significati volutamente rigidi:

• Planned significa che la superficie è nota ma manca ancora di copertura completa.
• Documented significa che esiste prosa utile, ma mancano ancora gli screenshot di produzione attuali o una revisione di accuratezza end-to-end.
• Verified significa che la pagina di funzionalità relativa è verificata e supportata da screenshot di produzione registrati.

Esegui npm --prefix docs-site run coverage:complete per il cancello di release. Fallisce finché ogni superficie inventariata non è verificata; le normali build incrementali del manuale continuano a riportare i conteggi rimanenti senza bloccare i commit di dimensione ragionevole.

Aggiungi un caso di screenshot

1. Aggiungi o riusa un harness deterministico di screenshot Flutter.
2. Registra il caso e le sue quattro immagini sorgente in docs-site/metadata/screenshot-cases.json.
3. Metti la copia dimostrativa visibile dietro manualScreenshotText(...) per ogni locale supportato, quando non è già fornita dai file di localizzazione dell'app.
4. Cattura ogni locale nella directory locale di staging ignorata da git (make manual_screenshots); la CI pubblica il risultato nel bucket R2.
5. Genera e valida il manifesto dei media.
6. Riferisci il caso con <ManualScreenshot caseId="…" alt="…" /> su ogni pagina di lingua.

Ogni screenshot dell'app in una pagina autorata deve usare ManualScreenshot. I link diretti ai media degli screenshot — vecchie immagini lotti-docs o il bucket R2 stesso — falliscono la validazione del manuale perché non possono seguire la scelta globale Mobile/Desktop o il tema light/dark del manuale.

Ogni caso automatizzato deve fornire le varianti mobile-light, mobile-dark, desktop-light e desktop-dark in ogni locale pubblicato. Il componente del manuale sceglie lingua e tema corrispondenti. Cambiare Mobile/Desktop su qualsiasi immagine aggiorna subito ogni screenshot e persiste tra le pagine e le schede del manuale aperte.

Pubblica un rilascio

La sorgente del manuale non viene copiata per ogni versione dell'app. Il tag di rilascio dell'app conserva già la sua sorgente esatta. La pubblicazione è un'esecuzione manuale del workflow con la versione di marketing e il deploy abilitato: la CI risolve il tag dell'app più recente di quella versione, costruisce il sito e il suo catalogo di screenshot dal tag, carica entrambi in uno storage versionato immutabile e ridistribuisce il sito con tutte le versioni fianco a fianco. Gli snapshot di rilascio non vengono mai sovrascritti. Il dropdown delle versioni legge un catalogo live scritto a ogni deploy, quindi anche i manuali più vecchi elencano i rilasci arrivati dopo di loro.