Plán rozvoje

PLANNING.md popisuje dva kanonické záznamy, jak se odvozuje stav, jak důkazy brání dokončení a jak se model promítá. Tento dokument pokrývá vrstvu nad tím: graf mezi milníky, který rozhoduje, jakých výsledků lze vůbec dosáhnout.

Plán rozvoje není dokument. Je to projekce stavu milníků.

majordomus plan roadmap        # the sequence, with now and next
majordomus plan rgraph         # the same graph as Mermaid
majordomus plan roadmap --json # the same, for a generator

Nic v tomto souboru není plán rozvoje. Spusťte příkaz.

Dva grafy, záměrně ne jeden

Graf práce je úkol k úkolu uvnitř milníku: co smí worker provést dál. Je předmětem PLANNING.md.

Graf plánu rozvoje je od milníku k milníku: které výsledky jsou dosažitelné a v jakém pořadí. Jeho hranami jsou depends_on milníku.

Zůstávají oddělené, protože odpovídají na různé otázky pro různé čtenáře. Jejich sloučení by z „co mám dělat dnes ráno“ a „co letos stavíme“ udělalo týž dotaz.

Identita je slug a release se odvozuje

id: runtime-adapters

Milník nenese verzi. URL stránky milníku, odkaz tvrzení na něj a jeho vazba na GitHub se klíčují na slugu, takže se nic nerozbije, když se plán přeuspořádá nebo rozdělí. Typované version: plan validate odmítne jako neznámý klíč (ADR 0166): psalo se ručně, než projekt měl releasy, a rozcházelo se s releasy, ve kterých vyšlo.

Release, který nesl milník, je fakt o záznamech releasů, čtený jako released_in v plan roadmap (sloupec RELEASED, pole released_in v --json):

• poslední přijatý úkol milníku je jeho úkol DONE s nejpozdějším completed_at;
• jeho merge se najde přes commit, který toto razítko zapsal, a jinak podle posledního merge, jehož zpráva jmenuje úkol;
• released_in je první záznam o release (.ai/repo/releases/v*.yaml, sledované prohlášení o tagu vMAJOR.MINOR.PATCH), v pořadí verzí, jehož commit: jej obsahuje: git merge-base --is-ancestor <merge> <commit>. Pre-release nebo pojmenovaný tag není release a tag bez záznamu také ne.

Záznamy a ne tagy, protože odvozená data nesmějí záviset na refech mimo strom: odpověď je funkcí commitu a mění se jen tehdy, když přistane záznam, v pull requestu se záznamem, který stejně odvozuje znovu. Releasy před prvním záznamem (v0.3.1) žádný nemají, takže milník dokončený před ním se čte jako v0.3.1, nejdřívější release, který tato vrstva zaznamenává.

Milník, který není DONE nebo jehož commit žádný záznam dosud neobsahuje, se čte jako unreleased. Shellový engine (mj_pj_m_released_in v lib/project.sh) a spustitelný soubor (plan::released_in) na něj odpovídají příkaz po příkazu a případ 99 je drží shodné.

Nic nesmí odvozovat druh záznamu z tvaru jeho id. mj_pj_is_milestone se ptá načteného modelu, protože id milníku je slug a id úkolu se od něj podle zápisu rozlišit nedá.

Kontrola

Každý krok je podmíněn tím, že předchozí je skutečný.

Tato věta dřív stála pod ručně psanou tabulkou. Teď je to invariant:

Milník, jehož závislosti nejsou všechny DONE, je BLOCKED, ať jeho vlastní úkoly říkají cokoli. Dokončení každého úkolu uvnitř milníku ho nepřenese přes předpoklad, kterého nebylo dosaženo.

Dosažení ACTIVE, VERIFY nebo DONE přes nesplněnou závislost není stav k zobrazení. Je to rozpor, hlášený jako milestone_premature.

Kontrola běží v pořadí podle ranku, takže blok se kaskáduje celým řetězcem, ne jen o jeden krok.

Pořadí plyne z grafu

Pořadí plánu rozvoje je topologická hodnost každého milníku v grafu závislostí. Pole order: rozhoduje jen shody uvnitř hodnosti; nemůže milník posunout za to, co vyžaduje.

Nikde neexistuje seznam verzí — ani v záznamech, generátoru, na webu, ani zde. Přidání souboru milníku jej zařadí do plánu rozvoje.

Co graf plánu rozvoje odmítá

Stejná odmítnutí, jaká má graf práce, o úroveň výš, každé jménem:

bash test/run.sh 48_roadmap_graph

Tvrzení

Milník může jmenovat tvrzení, která by posunul:

claims:
  - runtime-adapters

To jsou id docs/CLAIMS.yaml. Vztah se deklaruje, nikdy nevyvozuje z toho, že číslo verze odpovídá nějaké próze.

Navázání tvrzení na milník ho nepovyšuje. Tvrzení se stane guaranteed stávající cestou a jen touto cestou — implementací, behaviorálním testem a CI, které ten test spouští. Přijetí milníku není důkazem o tvrzení.

Milník, který byl dodán dříve, než model existoval

Milník bez úkolů je PLANNED — výsledek, který nikdo neprovádí — pokud nenese vlastní evidence; v takovém případě byl výsledek dosažen mimo tento model a je zaznamenán jako dosažený.

Tak je reprezentována práce dodaná před vznikem modelu, aniž by se pro ni vymýšlely úkoly. Je to jediná cesta k DONE, která neprochází úkolem, a přesto prochází důkazy. Její released_in se čte skrze tyto důkazy: commit, který napsal nejnovější recorded_at z ní, stojí tam, kde by stál merge úkolu, takže milník se dodává v prvním záznamu o release, který jej obsahuje (foundation, zaznamenaný před v0.3.1, čte v0.3.1).

Nahrazeno, ne smazáno

Milník, který byl nahrazen, nastaví superseded_by: a odvodí SUPERSEDED. Historie plánu rozvoje se uchovává, nepřepisuje; přijatý milník se nikdy nevymaže úpravou.

Přidání milníku

Napište jeden soubor:

.ai/repo/project/milestones/<slug>.yaml

Objevuje se v plan roadmap, v plan rgraph, v generovaných datech webu i v projekci na GitHub, protože každé z nich čte adresář. Žádný seznam rout, položka navigace, pole verzí ani větev generátoru žádný milník nejmenuje.

test/cases/48_roadmap_graph.sh uprostřed testu přidá milník a asertuje, že se objeví, aniž by se upravil jakýkoli seznam.

Viz také

• PLANNING.md — záznamy, odvozený stav, vlny, důkazy, projekce
• DOGFOODING.md — proč je tento repozitář povinen jej používat