Contribuire alla documentazione

Prerequisiti

• Node.js 22;
• Python 3.12;
• un checkout pulito del repository;
• una Story GitHub autorizzata e in scope.

Preparazione

npm ci
python3 -m venv .venv-docs
source .venv-docs/bin/activate
python3 -m pip install --require-hashes --requirement requirements-docs.txt

Le dipendenze Python sono bloccate con versione e hash. Mermaid è una dipendenza npm esatta: il comando di preparazione copia il runtime installato in un asset locale ignorato da Git, poi verifica che il contenuto corrisponda alla dipendenza bloccata.

Scrittura

1. Scrivere navigazione, prosa, avvisi e didascalie in italiano.
2. Conservare invariati comandi, file path, campi API e nomi di prodotto quando tradurli ridurrebbe la precisione.
3. Usare collegamenti Markdown relativi verso file presenti nel portale.
4. Usare blocchi fenced mermaid senza direttive di configurazione, link interattivi o HTML eseguibile.
5. Non inserire informazioni sensibili o evidenza operativa privata.

Validazione e anteprima

npm run docs:validate
npm run docs:build
npm run docs:serve

La validazione fallisce su pagine obbligatorie mancanti, navigazione non italiana, collegamenti o ancore interni non risolti, Mermaid non valido, configurazioni Mermaid non sicure, possibili dati sensibili e file tracciati in site/.

L'anteprima è disponibile su http://127.0.0.1:8000/. Interromperla prima di cambiare ambiente virtuale. Non aggiungere al commit site/, .venv-docs/ o l'asset Mermaid preparato.