From 0a5e8c4da8022cf0917374635ed775d27d32dd73 Mon Sep 17 00:00:00 2001 From: Andres Rodriguez Date: Tue, 14 Jul 2026 10:47:44 -0700 Subject: [PATCH] Document docs CI and deployment invariants --- AGENTS.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 52f3c75e8c..3a98ccb3d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,3 +48,32 @@ Documentation is written in Quarto Markdown (`.qmd`). Key conventions: - Variables use `{{< var name >}}` syntax (defined in `_variables.yml`) - Cross-references use relative paths ending in `.qmd` - Images are stored alongside their `.qmd` files + +## Pull requests and release notes + +Documentation pull requests must follow the repository's release-note policy: + +- Internal workflow, tooling, or maintenance changes use the `internal` label. +- External changes use an appropriate release-note label and include content in the pull request's release-notes section. + +The required `validate` check is the pull-request feedback gate. For ordinary content changes, it renders only safely targetable changed pages and assets and builds the preview on top of the validated staging site. It falls back to a complete preview render for changes that can have global or ambiguous effects, including Quarto configuration or metadata, generated content, deletions, and renames. + +## Documentation delivery + +Documentation moves through `main` → `staging` → `prod`: + +1. Pull requests into `main` receive preview validation and normal review. +2. After merge, the staging workflow renders the complete staging site and the prospective production site in parallel. +3. The prospective production build runs the complete production-profile validation and uploads an immutable artifact keyed to the exact Git tree that a `staging` → `prod` merge will create. +4. The production workflow deploys only that exact-tree artifact from a successful staging workflow run. If the artifact is missing, expired, or came from another workflow, production deployment must fail before loading AWS credentials or modifying production. + +The merge-queue `validate` bridge does not render the site again. It records that the pull-request revision passed preview validation; the complete production safety boundary is the post-merge staging artifact. + +## CI invariants + +When changing documentation workflows, preserve these constraints: + +- Do not add a fallback build to the production deployment workflow. Missing validated artifacts must fail closed. +- Keep full Git history available when preparing the prospective production tree. A shallow checkout cannot establish the shared `staging`/`prod` history and causes Git to reject the merge as unrelated histories. +- Keep targeted preview runs cancelable so a newer commit supersedes obsolete work. +- Treat preview rendering and production validation as different responsibilities: previews provide fast author feedback; only the complete post-merge production-profile build can authorize a production artifact.