Restructure docs: docs-first, SSOT, one ADR per decision
- Add docs/README.md as the index of all documentation. - Split the 52 DEC entries of decisioni-e-limiti.md into docs/adr/ADR-NN files (same numbers), add ADR-53 (audit log), TEMPLATE.md and an ADR index with a feature -> ADR table. - Rename decisioni-e-limiti.md to limiti-noti.md (LIM only) and rewrite all DEC-nn references as links to the ADRs. - Document the docs-first / SSOT / ADR rules in processo-di-modifica.md and map the docs in CLAUDE.md and README.md. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
7ba8e22bb4
commit
b424f670c5
76 files changed
+2147
-1530
No files matched your search
@@ -1,5 +1,35 @@
|
||||
# Processo di modifica: dalla documentazione al codice
|
||||
|
||||
L'indice di tutta la documentazione è [README.md](README.md). Questo documento
|
||||
ne fissa le regole di lavoro.
|
||||
|
||||
## Principi: docs-first, SSOT, ADR
|
||||
|
||||
- **Docs-first.** Si cambia prima la documentazione, poi il codice; spec,
|
||||
codice e test stanno nello stesso commit.
|
||||
- **SSOT.** Ogni informazione ha un solo proprietario e gli altri documenti
|
||||
rimandano a lei per ID senza ripeterla:
|
||||
|
||||
| Informazione | Proprietario |
|
||||
|---|---|
|
||||
| Perché una scelta (contesto, alternative, conseguenze) | un ADR in [adr/](adr/README.md) |
|
||||
| Che cosa deve fare il software (regola verificabile) | il requisito `PREFISSO-NN` del documento di dominio |
|
||||
| Schema, stati, vincoli | `DAT` in [modello-dati.md](modello-dati.md) |
|
||||
| Soglie e rischi di sicurezza | `SEC` in [sicurezza.md](sicurezza.md) |
|
||||
| Eventi di audit | `AUD` in [audit-log.md](audit-log.md) |
|
||||
| Come lo fa | il codice (riferimento `percorso:funzione`) |
|
||||
| Limiti accettati | `LIM` in [limiti-noti.md](limiti-noti.md) |
|
||||
| Difetti trovati e corretti | [storico-bug.md](storico-bug.md) |
|
||||
|
||||
- **Un ADR per ogni funzionalità.** Una funzionalità nuova, o un cambio di
|
||||
scelta in una esistente, parte da un ADR scritto da [adr/TEMPLATE.md](adr/TEMPLATE.md):
|
||||
prossimo numero libero, stato *Proposta* finché non è approvato, poi
|
||||
*Accettata*. L'ADR elenca i requisiti che lo attuano; i requisiti citano
|
||||
l'ADR. Un ADR non si riscrive: se la scelta cambia se ne scrive uno nuovo e
|
||||
il vecchio passa a *Sostituita da ADR-MM*. Un nuovo ADR va aggiunto
|
||||
all'indice per area e alla tabella funzionalità → ADR di
|
||||
[adr/README.md](adr/README.md).
|
||||
|
||||
La cartella `docs/` è la **specifica** di PLM Lottery. Descrive cosa il
|
||||
software fa e perché; il codice è l'implementazione di questa specifica.
|
||||
Ogni modifica di comportamento parte da qui.
|
||||
@@ -82,15 +112,18 @@ fa il codice oggi:
|
||||
| `ELC` | [connessione-electrum.md](connessione-electrum.md) | Connessione alla rete |
|
||||
| `AUD` | [audit-log.md](audit-log.md) | Eventi del registro di audit |
|
||||
| `OPS` | [operativita.md](operativita.md) | Procedure operative |
|
||||
| `DEC` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Decisioni di progetto |
|
||||
| `LIM` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Limiti noti accettati |
|
||||
| `ADR` | [adr/](adr/README.md) | Decisioni di progetto (un file per decisione) |
|
||||
| `LIM` | [limiti-noti.md](limiti-noti.md) | Limiti noti accettati |
|
||||
|
||||
## Il ciclo di una modifica
|
||||
|
||||
0. **Scegliere.** Se la modifica è una funzionalità o una scelta nuova, si
|
||||
scrive o aggiorna l'ADR (e si approva) prima di toccare i requisiti.
|
||||
1. **Modificare la specifica.** Si cambia il testo del requisito in `docs/`
|
||||
(o se ne aggiunge uno nuovo con il prossimo numero libero). Se la modifica
|
||||
tocca una decisione (`DEC-*`) o un limite (`LIM-*`), si aggiorna anche
|
||||
quello.
|
||||
tocca una decisione (`ADR-*`) o un limite (`LIM-*`), si aggiorna anche
|
||||
quello; se introduce una funzionalità o una scelta nuova, si scrive prima
|
||||
il relativo ADR (vedi sotto).
|
||||
2. **Individuare l'impatto.** I riferimenti *Codice* e *Test* del requisito
|
||||
dicono dove intervenire. Si cercano anche le altre occorrenze
|
||||
dell'identificativo nel repository (`git grep RND-11`) e i requisiti di
|
||||
|
||||
Reference in new issue
Block a user