Účel
Zpráva, která říká „hotovo“, spojuje tři různé fakty: změna existuje, změna byla zkontrolována a kontrola ukázala, že funguje. Čtenáři jednají podle třetího a obvykle dostanou první. Tato dovednost dělá rozdíl součástí gramatiky zprávy: každé tvrzení nese stav, který důkazy podporují, a stav bez důkazů není k dispozici.
Kdy použít
Každá zpráva, podle které bude jednat jiný pracovník nebo člověk: tělo předávky, závěrečná zpráva úlohy, popis pull requestu, odpověď na „je to hotovo?“. Sekce Verification promptu předávky je psána tímto způsobem.
Postup
1. Pište tvrzení, ne příběh
Vypište, co práce tvrdí, že je nyní pravda, jedno tvrzení na řádek, každé dost malé, aby se dalo ověřit jedním příkazem: „skills verify končí s 0 na masteru“, ne „dovednosti jsou hotové“.
2. Připojte důkazy, které jste pozorovali
U každého tvrzení příkaz, který běžel, jeho návratový kód a řádek výstupu, který o něm rozhoduje. Důkazem je jen to, co běželo v této relaci, nebo co ukazuje zaznamenané provedení (ledger důkazů, běh CI, který jste přečetli). Příkaz, o kterém očekáváte, že projde, důkaz není.
3. Označ stav
- OVĚŘENO — o tvrzení rozhodují důkazy, při commitu, o kterém report je.
- ČÁSTEČNĚ — nějaký důkaz existuje a pojmenovaná část tvrzení není pokryta: jiná platforma, kontrola, která neběžela, zastaralý běh, nevyzkoušená plocha. Pojmenujte tu část.
- BLOKOVÁNO — tvrzení nelze nyní ověřit. Uveďte, co jej blokuje (chybějící nástroj, fronta, rozhodnutí, které není vaše) a co by jej odblokovalo.
Při pochybnosti mezi dvěma stavy vezměte ten slabší.
4. Seřadit a uzavřít
Dejte BLOCKED první, pak PARTIAL, pak VERIFIED, aby čtenář narazil nejdřív na to, co ho potřebuje. Zakončete jedním řádkem na mezeru: příkaz ke spuštění nebo rozhodnutí k učinění a kdo je může učinit.
Výstup
Tabulka, pak mezery:
| state | claim | důkazy (příkaz, návratový kód, rozhodující výstup) |
|---|
Žádné tvrzení se neobjeví bez stavu, žádné tvrzení VERIFIED se neobjeví bez příkazu a souhrnný řádek zprávy počítá každý stav zvlášť, místo aby řekl „hotovo“.