0 Fork 0

Files

T

davideandClaude Sonnet 5.5 ccfa00ff52 Aggiungi docs-as-code: indice Diátaxis, nuovi doc e controllo automatico

Nuovi doc: tutorial-primo-giro, risoluzione-problemi, sviluppo, rilascio,
glossario e registro delle decisioni (docs/decisioni, 6 ADR). docs/README.md
e' l'indice per categoria e la tabella delle fonti uniche; il README di
root rimanda a sviluppo/rilascio invece di duplicarli.

scripts/CheckDocs.cs verifica link e ancore, <Version> contro CHANGELOG,
copertura di architettura.md e presenza di ogni doc nell'indice;
.markdownlint-cli2.jsonc configura il lint Markdown.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

2026-10-02 08:05:10 +02:00

2.4 KiB

Raw Permalink Blame History

Guida per chi sviluppa

Come lavorare sul codice e sui doc. Per capire com'è fatto il programma parti da architettura.md; per rilasciare vedi rilascio.md.

Requisiti

Windows e .NET 10 SDK.
Accesso alla share X:\ solo per indicizzare davvero; i test non ne hanno bisogno.
Node.js (per npx markdownlint-cli2, solo per i doc).

Build e avvio

cd PrepStep
dotnet build -c Release
dotnet run -c Release

In sviluppo cad_index.db si cerca nella cartella di build, non nella radice del repo: vedi db-cad-index.md.

Test

cd PrepStep.Tests
dotnet test

I test xUnit chiamano gli internal del progetto principale grazie a InternalsVisibleTo. I .asm dei test si costruiscono byte per byte con piccoli helper invece di versionare file binari: ogni caso strano trovato sulla share diventa un test minimale. Elenco dei file di test in architettura.md.

Script standalone

Si lanciano dalla root del repo, mai da dentro PrepStep/ (che è un WinExe: dotnet run avvierebbe la GUI e resterebbe bloccato). Elenco in architettura.md.

dotnet run scripts/Query.cs -- cad_index.db "SELECT COUNT(*) FROM files"

Documentazione come codice

I doc stanno in git, si modificano nello stesso commit del codice e si verificano a mano:

dotnet run scripts/CheckDocs.cs   # link, ancore, versione/CHANGELOG, copertura dei doc
npx markdownlint-cli2             # stile Markdown (.markdownlint-cli2.jsonc)

Regole di scrittura:

Una sola fonte per ogni informazione, altrove un link (tabella in README.md).
Ogni doc ha un solo scopo (Diátaxis): non mescolare istruzioni, riferimento e motivazioni.
Un cambiamento strutturale (fasi, formato .asm, schema DB, criterio di scelta di un file) aggiorna i doc e il CHANGELOG nello stesso commit.
Se la modifica nasce da un fallimento reale di Creo scrivi il sintomo: i messaggi di Creo non nominano il file né la causa (esempio: §7.3-7.5 di formato-asm-record.md).
Una scelta con alternative reali non banali merita una voce in decisioni/.
Un nuovo .cs va descritto in architettura.md e un nuovo doc elencato in docs/README.md: CheckDocs.cs lo verifica.

2.4 KiB Raw Permalink Blame History