Specs, documentos e revisões

Uma spec é uma unidade de trabalho numerada com até cinco documentos e um estado.

O servidor numera as specs (001, 002, …) quando as cria com create_spec, que recebe um slug de uma a quatro palavras em minúsculas unidas por hífenes. Cada spec recebe ainda um nome de ramo como 004-diesel-orm. A spec ativa é a spec não arquivada com o número mais alto, e get_active_spec devolve-a.

Documentos

DocumentoO que contém
specO quê e porquê, com os requisitos funcionais (FR-1, FR-2, …).
planComo será construído.
tasksPequenas tarefas com fase, indicador de paralelismo, referências a FR e uma verificação Done when.
researchDescobertas que respondem a perguntas em aberto.
validationCada requisito e o teste que o cobre.

Estado

Uma spec está em draft, clarified, approved ou archived. As passagens permitidas são de draft para clarified, de clarified para approved, de clarified de volta para draft e de approved de volta para draft. Os owners podem arquivar uma spec, e uma spec arquivada já não pode mudar de estado.

Só uma spec clarified pode ser aprovada, e não enquanto tiver marcadores abertos (veja Tarefas e marcadores). Um projeto pode também exigir várias aprovações e impedir que aprove uma spec quem contribuiu para ela. Uma passagem recusada indica quais os destinos permitidos.

Revisões e conflitos

O put_document escreve o corpo completo de um documento como uma nova revisão; nada é alterado no local. Quando o documento já existe, indique expected_revision, a revisão em que a sua edição se baseia. Se outra pessoa escreveu primeiro, a escrita é recusada com conflict e a revisão atual, para que o agente a leia, una as alterações e escreva de novo. Nada é sobrescrito e ambas as alterações ficam no histórico.

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

O list_revisions lista as revisões de um documento ou da constituição, da mais recente para a mais antiga, e o get_revision lê uma pelo seu id.