84 lines
4.4 KiB
Markdown
84 lines
4.4 KiB
Markdown
 
|
# Processo di modifica: dalla documentazione al codice
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
## Convenzione dei requisiti
|
||
|
|
|
||
|
|
Ogni regola verificabile ha un **identificativo stabile**, nella forma
|
||
|
|
`PREFISSO-NN`, scritto in grassetto all'inizio del punto che la descrive,
|
||
|
|
seguito dai riferimenti all'implementazione e, dove esistono, ai test:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
- **[RND-11]** Alla scadenza il round passa subito a `closing`: da quel momento
|
||
|
|
nessuna scommessa è più accettata.
|
||
|
|
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
|
||
|
|
*Test:* `tests/unit/test_scheduler.py`
|
||
|
|
```
|
||
|
|
|
||
|
|
Regole della convenzione:
|
||
|
|
|
||
|
|
- **Un identificativo non si riusa mai.** Un requisito eliminato resta nel
|
||
|
|
documento come `~~[RND-11]~~ Rimosso: <motivo>`, così i riferimenti già
|
||
|
|
scritti (commenti, commit, test) non puntano a una regola diversa.
|
||
|
|
- **I numeri non si rinumerano.** Un requisito nuovo prende il numero
|
||
|
|
successivo al più alto del suo prefisso, anche se finisce in mezzo al testo.
|
||
|
|
- **I riferimenti al codice** sono `percorso:funzione` o `percorso:Classe.metodo`,
|
||
|
|
mai numeri di riga (cambiano a ogni modifica).
|
||
|
|
- Il testo descrittivo che non contiene regole (introduzioni, spiegazioni,
|
||
|
|
esempi) non ha identificativo.
|
||
|
|
|
||
|
|
### Prefissi
|
||
|
|
|
||
|
|
| Prefisso | Documento | Ambito |
|
||
|
|
|---|---|---|
|
||
|
|
| `ARC` | [architettura.md](architettura.md) | Struttura del codice, processi, frontend, test |
|
||
|
|
| `DAT` | [modello-dati.md](modello-dati.md) | Tabelle, campi, stati, vincoli |
|
||
|
|
| `API` | [api.md](api.md) | Endpoint, formato delle risposte, codici di errore |
|
||
|
|
| `SEC` | [sicurezza.md](sicurezza.md) | Chiavi, autenticazione, limiti, rischi accettati |
|
||
|
|
| `REG` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Registrazione e account |
|
||
|
|
| `DEP` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Depositi e saldo |
|
||
|
|
| `BET` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Scommesse |
|
||
|
|
| `WDR` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Prelievi |
|
||
|
|
| `RND` | [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | Round, estrazione, pagamento |
|
||
|
|
| `TX` | [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | Ciclo di vita delle transazioni, RBF, riconciliazione |
|
||
|
|
| `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 |
|
||
|
|
|
||
|
|
## Il ciclo di una modifica
|
||
|
|
|
||
|
|
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.
|
||
|
|
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
|
||
|
|
altri documenti che dipendono dallo stesso codice.
|
||
|
|
3. **Implementare e testare.** Si modifica il codice e si aggiunge o aggiorna
|
||
|
|
un test che verifica il nuovo comportamento. Il test cita l'identificativo
|
||
|
|
nella sua docstring.
|
||
|
|
4. **Allineare i riferimenti.** Se il codice si è spostato (funzione
|
||
|
|
rinominata, file diviso), si aggiornano i riferimenti *Codice* del
|
||
|
|
requisito.
|
||
|
|
5. **Commit unico.** Specifica, codice e test entrano nello stesso commit,
|
||
|
|
con l'identificativo nel messaggio (ad esempio
|
||
|
|
`Close the round on its own deadline (RND-11)`).
|
||
|
|
|
||
|
|
Una correzione di bug che non cambia la specifica (il codice non faceva ciò
|
||
|
|
che il documento già diceva) segue la convenzione `B-nn` descritta in
|
||
|
|
[storico-bug.md](storico-bug.md): numero successivo, commit dedicato, test di
|
||
|
|
regressione. Se invece il bug rivela che la specifica era sbagliata o
|
||
|
|
incompleta, si corregge prima la specifica, come per qualunque altra modifica.
|
||
|
|
|
||
|
|
## Documenti della specifica
|
||
|
|
|
||
|
|
Il punto d'ingresso è [come-funziona.md](come-funziona.md). Le guide
|
||
|
|
operative ([setup.md](setup.md), [running-the-server.md](running-the-server.md),
|
||
|
|
[guida-utente.md](guida-utente.md), [guida-admin.md](guida-admin.md)) non
|
||
|
|
contengono requisiti: descrivono come usare il software, e si aggiornano
|
||
|
|
quando la specifica cambia qualcosa di visibile.
|