Okamžik
Někdo zkopíruje příkaz ze stránky getting-started. Skončí s exit 2 a chybou použití u volby, která byla na jaře přejmenována. Stránka nebyla špatně dost dlouho na to, aby si někdo stěžoval, a byla špatně pro každého, kdo ji vyzkoušel.
Proč k tomu dochází
Příklad v dokumentu je řetězec. Nic jej nespouští, takže nic nepozná, že přestal fungovat. Příkaz, který popisuje, žije v kódu, který se z dobrých důvodů mění, a řetězec se na těchto změnách nepodílí.
Proč to lepší model nevyřeší
Worker čtoucí dokumentaci věrně zopakuje rozbité vyvolání a pak diagnostikuje selhání, které způsobilo. Dokumentace byla vstup a byla špatně; žádná schopnost se z chybné specifikace nezotaví bez placení za oklikou.
Co to stojí
Nejdražší minuta v projektu: první, pro někoho, kdo se rozhoduje, zda je udržován. Poté stálé kapání dotazů na podporu, na které je odpověď „dokumentace je zastaralá“.
Co Majordomus dělá
Příkazová řádka je deklarována jednou a příklady jsou deklarovány vedle ní jako vektory argumentů s tím, co musí každý ukázat — návratový kód, úryvek výstupu, JSON pointer, který se musí přeložit. Testy samotného cratu spouštějí každý z nich proti sestavené binárce v jednorázovém repozitáři. Referenční dokument, strojově čitelný model příkazů a stránky webu jsou vykreslení téže deklarace, takže přejmenování dorazí ke všem najednou. Příkaz, který lze spustit a nenese žádný spouštěný příklad, validací neprojde.
Před a po
before docs: majordomus check --explain-all (renamed in April)
after every example is argv + Expect, executed by the suite:
$ cargo test --test cli_examples
running 27 examples against the built binary ... okCo nedělá
Nekontroluje prózu a nepozná, zda je příklad užitečný. Příklad, který přestal fungovat, činí selháním testu, a ne objevem čtenáře.