Specs, Dokumente und Revisionen
Eine Spec ist eine nummerierte Arbeitseinheit mit bis zu fünf Dokumenten und einem Status.
Der Server nummeriert Specs (001, 002, …), wenn du sie mit create_spec anlegst; dafür gibst du einen Slug aus ein bis vier kleingeschriebenen, mit Bindestrichen verbundenen Wörtern an. Jede Spec erhält außerdem einen Branch-Namen wie 004-diesel-orm. Die aktive Spec ist die nicht archivierte Spec mit der höchsten Nummer; get_active_spec liefert sie.
Dokumente
| Dokument | Inhalt |
|---|---|
spec | Was und warum, mit den funktionalen Anforderungen (FR-1, FR-2, …). |
plan | Wie es gebaut wird. |
tasks | Kleine Aufgaben mit Phase, Parallel-Markierung, FR-Verweisen und einer Done-when-Prüfung. |
research | Erkenntnisse, die offene Fragen beantworten. |
validation | Jede Anforderung und der Test, der sie abdeckt. |
Status
Eine Spec ist draft, clarified, approved oder archived. Erlaubt sind draft zu clarified, clarified zu approved, clarified zurück zu draft und approved zurück zu draft. Owner können eine Spec archivieren, und eine archivierte Spec kann ihren Status nicht mehr ändern.
Nur eine clarified-Spec kann genehmigt werden, und nicht, solange sie offene Marker hat (siehe Aufgaben und Marker). Ein Projekt kann außerdem mehrere Genehmigungen verlangen und denen, die zu einer Spec beigetragen haben, das Genehmigen untersagen. Ein abgelehnter Wechsel nennt die erlaubten Ziele.
Revisionen und Konflikte
put_document schreibt den vollständigen Text eines Dokuments als neue Revision; nichts wird an Ort und Stelle geändert. Existiert das Dokument bereits, übergib expected_revision, die Revision, auf der deine Änderung beruht. Hat jemand anderes zuerst geschrieben, wird der Schreibvorgang mit conflict und der aktuellen Revision abgelehnt, sodass der Agent sie liest, zusammenführt und erneut schreibt. Nichts wird überschrieben, und beide Änderungen bleiben in der Historie.
list_revisions listet die Revisionen eines Dokuments oder der Verfassung, neueste zuerst, und get_revision liest eine per ID.