Specs, documentos y revisiones

Una spec es una unidad de trabajo numerada con hasta cinco documentos y un estado.

El servidor numera las specs (001, 002, …) cuando las creas con create_spec, que recibe un slug de una a cuatro palabras en minúsculas unidas por guiones. Cada spec recibe además un nombre de rama como 004-diesel-orm. La spec activa es la spec no archivada con el número más alto, y get_active_spec la devuelve.

Documentos

DocumentoQué contiene
specQué y por qué, con los requisitos funcionales (FR-1, FR-2, …).
planCómo se construirá.
tasksTareas pequeñas con fase, marca de paralelo, referencias a FR y una comprobación Done when.
researchHallazgos que responden a preguntas abiertas.
validationCada requisito y la prueba que lo cubre.

Estado

Una spec está en draft, clarified, approved o archived. Los cambios permitidos son de draft a clarified, de clarified a approved, de clarified de vuelta a draft y de approved de vuelta a draft. Los owners pueden archivar una spec, y una spec archivada ya no puede cambiar de estado.

Solo una spec clarified puede aprobarse, y no mientras tenga marcadores abiertos (consulta Tareas y marcadores). Un proyecto también puede exigir varias aprobaciones y prohibir que aprueben una spec quienes han contribuido a ella. Un cambio rechazado indica qué destinos están permitidos.

Revisiones y conflictos

put_document escribe el cuerpo completo de un documento como una revisión nueva; nada se modifica en el sitio. Cuando el documento ya existe, indica expected_revision, la revisión en la que se basa tu edición. Si otra persona escribió antes, la escritura se rechaza con conflict y la revisión actual, de modo que el agente la lee, fusiona y vuelve a escribir. Nada se sobrescribe y ambos cambios quedan en el historial.

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

list_revisions lista las revisiones de un documento o de la constitución, de la más reciente a la más antigua, y get_revision lee una por su id.