Účel
Zjistěte, co je o repozitáři pravda, než jej změníte. Worker, který se nepodíval, začne „pomáhat“ přidáním vrstvy, kterou nikdo nechtěl; tento postup dělá koukání explicitní, omezené a hlásitelné. Posuzuje realitu, ne styl: zda kód dělá to, co říkají dokumenty, zda jsou záruky podložené testy, zda vygenerované soubory odpovídají svým zdrojům a zda hranice, které repozitář deklaruje, jsou ty, které kód dodržuje.
Kdy použít
- před implementací úkolu, aby se zkontrolovalo, že repozitář je tam, kde to úkol předpokládá;
- na diffu nebo větvi, dříve než se označí za hotové;
- na subsystému nebo celém repozitáři, když je otázkou „co tu skutečně je“;
- na generovaných površích (dokumenty, projekce, data webu), když je podezření na drift.
Ne tato dovednost: psaní opravy, posouzení prózy z hlediska tónu nebo odhad pracnosti.
Postup
Procházejte sekce v pořadí. Každá jmenuje, co číst a na co se dívat. Zaznamenejte každý nález v okamžiku, kdy je pozorován, se souborem a řádkem, kde byl pozorován; nečekejte na konec, abyste rekonstruovali důkazy z paměti.
1. Rozsah a kontext
- Přečtěte si efektivní kontext pro každou cestu v rozsahu: kořenový instrukční soubor, platná pravidla a dokumenty s rozsahem od kořene dolů k adresáři (
majordomus context resolve <path>,majordomus rules list). Poznamenejte si, která pravidla vynucuje stroj a která jen recenzent; druhý druh je místo, kde se recenze vyplatí. - Stanovte množinu změn: větev a worktree, diff proti její bázi a historii souborů, kterých se dotýká. Čtěte okolní implementaci, ne jen změněné řádky; správný řádek ve špatné funkci je špatná změna.
- Uveďte ve zprávě rozsah přesně tak, jak byl posuzován. Cokoli mimo něj není pokryto a zpráva to říká.
2. Správnost
Hledejte chování, které je špatné teď nebo které se stane špatným, když prostředí poprvé nepůjde šťastnou cestou:
- porušená invariance, kterou repozitář uvádí (pravidlo, schéma, zdokumentovaná smlouva);
- nedokončený přechod stavu nebo záznam, který může zůstat napůl zapsaný;
- předpoklad, který kód činí a který jeho vstupy nezaručují;
- mezery v perzistenci: co se ztratí při restartu, při částečném selhání, při druhém běhu;
- neidempotentní mutace: příkaz, jehož druhé spuštění dělá něco jiného;
- skrytá záložní cesta, spolknutá chyba, „varuj a pokračuj“ tam, kde smlouva říká zastav;
- dvě místa, která drží touž pravdu a mohou se rozejít.
3. Kanonický a odvozený stav
U každého artefaktu v rozsahu rozhodněte, čím je: kanonický, generovaný, cachovaný, nebo nesouvisející. Pak ověřte, že odvozené lze deterministicky znovu vygenerovat z kanonických, že zastaralý se dá poznat příkazem, který selže, a že nic nezapisuje z projekce zpět do zdroje. Generovaný soubor, který nenese značku, že je generovaný, a nemá kontrolu, jež selže, když je zastaralý, je druhý zdroj pravdy, který čeká, až vznikne. Spusťte kontroly driftu repozitáře místo uvažování o nich.
4. Testování a důkazy
U každého chování, které změna tvrdí, najděte test, který ho zkouší zvenčí. Hledejte:
- tvrzení bez testu, nebo test, který ověřuje implementační detail místo chování;
- mock, který zastupuje právě tu hranici, o které je tvrzení;
- přeskočený nebo ignorovaný test, nebo kontrola, která hlásí úspěch, aniž by cokoli zkoumala;
- dokumentace, která slibuje víc, než testy dokládají;
- regrese, kterou by změna mohla zavést a kterou by nezachytil žádný případ.
Spusťte testy, které pokrývají rozsah. Výsledek testu, který jste nepozorovali, není důkaz.
5. Architektura a hranice
Zkontrolujte změnu proti hranicím, které repozitář deklaruje: obsah specifický pro providera na místech neutrálních vůči providerům, politika duplikovaná místo odkázaná, závislost přidaná bez uvedené potřeby, abstrakce s jedním volajícím, infrastruktura řešící problém, který nikdo nezaznamenal, a ručně udržovaná data, která šla odvodit. Pojmenujte deklaraci, kterou změna porušuje; hranice, která existuje jen v vkusu recenzenta, není nález.
6. Výkon
Jen tam, kde je výkon uvedeným kontraktem nebo horkou cestou: přečtěte důkazy z měření, hledejte opakované parsování, skenování nebo generování uvnitř smyčky a před závěrem měřte. Nález o výkonu bez měření je spekulace a takto se označuje.
7. Dokumentace
Zkontrolujte, že dokumenty popisující rozsah odpovídají jeho dnešnímu chování, že generované dokumenty jsou v synchronizaci se svými zdroji, že příklady stále běží, že stav záruky je poctivý a že nic v plánu rozvoje není popsáno jako existující schopnost.
Výstup
Report má tři části, v tomto pořadí.
Posuzovaný rozsah. Co bylo přečteno, které příkazy byly spuštěny a co záměrně pokryto nebylo.
Nálezy, nejzávažnější první. Každý nese:
| pole | obsah |
|---|---|
| závažnost | FAIL — musí se opravit, než je práce přijata; WARN — mělo by se opravit, neblokuje; INFO — pozorování bez požadované akce |
| název | jeden řádek |
| evidence | co bylo pozorováno, citováno nebo změřeno, s path:line |
| co je špatně | fakt, oddělený od závěru z něj vyvozeného |
| proč na tom záleží | selhání, které způsobuje, nebo invariant, který porušuje |
| nejmenší oprava | nejmenší změna, která to napraví |
| důkaz | test, kontrola nebo příkaz, který by ukázal, že oprava drží |
Označte každou větu jako jednu z: pozorovaný fakt, závěr, doporučení, spekulace. Nikdy nepovyšujte závěr na fakt tím, že štítek vynecháte.
Co bylo zkontrolováno a shledáno v pořádku. Oblasti postupu, které nepřinesly žádný nález, vyjmenované, aby prázdný seznam nálezů šlo odlišit od revize, která se nedívala. Pokud nejsou žádné podstatné nálezy, řekněte to přesně těmito slovy.
Nikdy nevymýšlejte nález, aby recenze vypadala užitečně, a nikdy žádný nevynechejte, aby změna vypadala připravená.