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:

- **[RND-11]** Al primo passo dello scheduler successivo alla scadenza il round
  passa a `closing`; le scommesse sono però rifiutate già dall'istante della
  scadenza ([BET-04]).
  *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.
Un solo proprietario per regola. Ogni regola ha l'identificativo in un solo documento; gli altri documenti che la citano rimandano a quell'ID invece di ripeterla con un ID proprio. Il documento di dominio (round, scommesse, transazioni…) è proprietario del comportamento, DAT dello schema, SEC delle soglie di sicurezza.
Niente formulazioni vaghe nelle regole. "Circa", "normalmente", "prima o poi" non compaiono in un requisito: si scrive la condizione esatta, con il nome della costante.

Requisiti non ancora implementati

La specifica può essere più avanti del codice: è il caso normale fra il passo 1 e il passo 3 del ciclo qui sotto. Un requisito che il codice non soddisfa ancora porta, subito dopo i riferimenti, una riga di stato e una che dice cosa fa il codice oggi:

- **[RND-33]** L'altezza del blocco di estrazione è fissata all'ingresso in
  `drawing` come `tip_at_close + 1` e non cambia più.
  *Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
  *Test:* —
  *Stato:* da implementare (B-73) · *Oggi:* si usa la punta vista al primo
  controllo utile, che può essere un blocco successivo.

Codice indica dove andrà l'implementazione (il file o la funzione esistente più vicina); Test è — finché il test non esiste.
Il B-nn rimanda alla voce di BUGS.md che descrive la correzione; l'ordine di implementazione è in piano-correzioni.md.
Quando il codice viene implementato, nello stesso commit si tolgono le righe Stato e Oggi e si completano Codice e Test. git grep "da implementare" elenca in ogni momento tutto ciò che manca.
Un requisito modificato (non nuovo) mantiene il suo identificativo: il testo descrive il comportamento atteso, Oggi quello attuale.

Prefissi

Prefisso	Documento	Ambito
`ARC`	architettura.md	Struttura del codice, processi, frontend, test
`DAT`	modello-dati.md	Tabelle, campi, stati, vincoli
`API`	api.md	Endpoint, formato delle risposte, codici di errore
`SEC`	sicurezza.md	Chiavi, autenticazione, limiti, rischi accettati
`REG`	registrazione-e-depositi.md	Registrazione e account
`DEP`	registrazione-e-depositi.md	Depositi e saldo
`BET`	scommesse-e-prelievi.md	Scommesse
`WDR`	scommesse-e-prelievi.md	Prelievi
`RND`	ciclo-di-vita-del-round.md	Round, estrazione, pagamento
`TX`	transazioni-e-riconciliazione.md	Ciclo di vita delle transazioni, RBF, riconciliazione
`ELC`	connessione-electrum.md	Connessione alla rete
`AUD`	audit-log.md	Eventi del registro di audit
`OPS`	operativita.md	Procedure operative
`DEC`	decisioni-e-limiti.md	Decisioni di progetto
`LIM`	decisioni-e-limiti.md	Limiti noti accettati

Il ciclo di una modifica

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.
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.
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.
Allineare i riferimenti. Se il codice si è spostato (funzione rinominata, file diviso), si aggiornano i riferimenti Codice del requisito.
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: 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. Le guide operative (setup.md, running-the-server.md, guida-utente.md, guida-admin.md) non contengono requisiti: descrivono come usare il software, e si aggiornano quando la specifica cambia qualcosa di visibile.

6.3 KiB Raw Blame History