Spec, documenti e revisioni

Una spec è un’unità di lavoro numerata con fino a cinque documenti e uno stato.

Il server numera le spec (001, 002, …) quando le crei con create_spec, che riceve uno slug di una–quattro parole minuscole unite da trattini. Ogni spec riceve anche un nome di branch come 004-diesel-orm. La spec attiva è la spec non archiviata con il numero più alto, e get_active_spec la restituisce.

Documenti

DocumentoCosa contiene
specCosa e perché, con i requisiti funzionali (FR-1, FR-2, …).
planCome sarà costruito.
tasksPiccole attività con fase, indicatore di parallelismo, riferimenti FR e un controllo Done when.
researchRisultati che rispondono alle domande aperte.
validationOgni requisito e il test che lo copre.

Stato

Una spec è draft, clarified, approved o archived. I passaggi consentiti sono da draft a clarified, da clarified ad approved, da clarified di nuovo a draft e da approved di nuovo a draft. Gli owner possono archiviare una spec, e una spec archiviata non può più cambiare stato.

Solo una spec clarified può essere approvata, e non finché ha marcatori aperti (vedi Attività e marcatori). Un progetto può anche richiedere più approvazioni e vietare di approvare una spec a chi ha contribuito a essa. Un passaggio rifiutato indica quali destinazioni sono consentite.

Revisioni e conflitti

put_document scrive il corpo completo di un documento come nuova revisione; nulla viene modificato sul posto. Quando il documento esiste già, passa expected_revision, la revisione su cui si basa la tua modifica. Se qualcun altro ha scritto prima, la scrittura viene rifiutata con conflict e la revisione corrente, così l’agente la legge, unisce e scrive di nuovo. Nulla viene sovrascritto e entrambe le modifiche restano nella cronologia.

HTTP 409
{ "code": "conflict", "message": "revision conflict: current revision is 42", "current_revision": 42 }

list_revisions elenca le revisioni di un documento o della costituzione, dalla più recente, e get_revision ne legge una per id.