From db8270e20c0f278c70bb30c9773b0f5441c4416a Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Sat, 22 Aug 2026 08:31:05 +0300 Subject: [PATCH] Document link validation enforcement boundaries --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..8fe9e9d55 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Netdata Learn Working Rules + +## Repository purpose + +This repository builds `learn.netdata.cloud` with Docusaurus and deploys the static result through +Netlify. Public-route validation must use rendered output; source Markdown alone is not proof that +a published path or fragment exists. + +## Link integrity contract + +Implementation status: policy specified; enforcement is unsupported until the standalone GitHub +jobs and corresponding branch-protection settings exist. + +Link validation has four distinct failure domains. Do not collapse them into one job or make a +Netlify build or deployment responsible for merge eligibility: + +- **Same-site links:** rendered links whose destination is `learn.netdata.cloud`, including + relative links, must resolve to an existing rendered path and fragment in the Learn build. + Validate them in a standalone required GitHub job outside Netlify. A same-site failure blocks + merging, while the deploy preview remains available. +- **Cross-Netdata-site links:** rendered links to another Netdata-owned site, including + `www.netdata.cloud`, run in a distinct standalone advisory GitHub job outside Netlify. Findings + remain visible but cannot block merging or deployment because coordinated source and target pull + requests may merge in either order. +- **New third-party links:** a third-party target URL present in the pull-request rendered output + but absent from the merge-base rendered output runs in a separate standalone advisory GitHub job + outside Netlify. The pull-request job checks only these newly introduced targets; its findings + cannot block merging or deployment. +- **Complete third-party reconciliation:** the full rendered third-party link inventory is checked + by a weekly scheduled job, not by every pull request. Workflow ownership, confirmation policy, + issue lifecycle, request policy, and optional AI-assisted repair require explicit user decisions + before implementation. + +## Change discipline + +- Keep the required same-site job independent from the advisory cross-site and third-party jobs. +- Do not weaken Docusaurus or CI link enforcement to make a pull request pass. Repair the owning + source or its generator. +- Generated documentation must be repaired through its owning producer and normal ingestion path; + do not hand-edit output that regeneration will replace. +- Use explicit file paths when staging changes; never stage the whole worktree.