davideandClaude Sonnet 5.5
ccfa00ff52
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>
67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# Guida per chi sviluppa
|
|
|
|
Come lavorare sul codice e sui doc. Per capire com'è fatto il programma parti da
|
|
[`architettura.md`](architettura.md); per rilasciare vedi [`rilascio.md`](rilascio.md).
|
|
|
|
## Requisiti
|
|
|
|
- Windows e [.NET 10 SDK](https://dotnet.microsoft.com/download).
|
|
- 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
|
|
|
|
```powershell
|
|
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`](db-cad-index.md#come-lapp-trova-il-db-allavvio).
|
|
|
|
## Test
|
|
|
|
```powershell
|
|
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`](architettura.md#test).
|
|
|
|
## 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`](architettura.md#script-standalone-scripts).
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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`](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`](formato-asm-record.md)).
|
|
- Una scelta con alternative reali non banali merita una voce in
|
|
[`decisioni/`](decisioni/README.md).
|
|
- Un nuovo `.cs` va descritto in `architettura.md` e un nuovo doc elencato in `docs/README.md`:
|
|
`CheckDocs.cs` lo verifica.
|