Co to znamená
Reference je zastaralá, pokud byla sestavena z jiného commitu, než za jaký je vydávána. To se odmítá dvakrát. Před publikací kontrola integrity odmítne strom, který jeho producent nesestavil z HEAD. Po publikaci veřejné ověření odmítne živou referenci, která chybí, je rozbitá nebo sestavená z jiného commitu, než který je nasazen — a ve workflow pro pages je toto ověření tvrdý krok, takže běh nasazení selže.
Princip
Commit jmenují dva svědci a nesdílejí zapisovatele. built_from v surface.json stromu je prohlášení producenta, přenesené do /build.json pod surfaces buildem webu. Vlastní stránka konstanty COMMIT v crate je prohlášení kompilátoru: rustdoc vykreslí hodnotu konstanty, kterou build.rs přečetl při posledním běhu — MAJORDOMUS_BUILD_COMMIT, když je nastaveno, jinak HEAD checkoutu. build.rs se nespustí znovu, když se pohne jen HEAD, takže producent předá buildu commit, který zaznamenává, a oba svědci pocházejí z jednoho buildu.
majordomus quality rustdoc porovnává built_from s HEAD. scripts/pages verify-rustdoc --commit SHA čte veřejný web, jakmile servíruje nasazený commit: povrch rustdoc v /build.json a /rustdoc/surface.json sestavené z tohoto commitu, úvodní stránku, která ho jmenuje, index knihovny odpovídající jako rustdoc se svými assety a stránku konstant, která ten commit jmenuje. Je to samostatná funkce vedle verify, která dál kontroluje samotné /build.json. scripts/ci/pages-check spouští totéž ověření jako sekci kontroly pages-live, při každé plné validaci a při finish.
Jak to vidět
majordomus quality rustdoc # built_from against HEAD
curl -fsS https://majordomus.dev/build.json | jq '.surfaces'
scripts/pages verify-rustdoc --commit "$(git rev-parse origin/master)" --timeout 0
scripts/ci/pages-check
bash test/run.sh 487_rustdoc_stalenessCo nepokrývá
Nečeká na GitHub: zda web vůbec poskytuje nasazený commit, řeší scripts/pages verify, jehož čekání je externí latence a je hlášeno, ne vynuceno. Neposuzuje, zda má každá položka svou stránku — to dělá rustdoc-complete před publikací. Běh zrušený před ověřovacím krokem nehlásí nic; pages-live se zeptá znovu při další validaci.
Proč existuje
Jediné veřejné ověření webu četlo /build.json, takže nasazení, které ztratilo celou referenci nebo nese referenci ze starší buildu, by ověřením prošlo. Úspěšné generování není důkaz, že bylo nasazeno správné: reference, která je na své veřejné URL špatná, je selhané nasazení ve stejném smyslu, jako když chybuje vlastní build GitHubu pro gh-pages, což workflow už červeně hlásí. test/cases/487_rustdoc_staleness.sh postaví strom z jednoho commitu a vydává jej za jiný.