Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (52 loc) · 4.05 KB

AGENTS.md

File metadata and controls

65 lines (52 loc) · 4.05 KB
Raw

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.

Learn link validation is repository-owned and self-contained. This repository owns its checker code, fixtures, workflows, schedule, artifacts, issue maintenance, branch-protection integration, repair automation, implementation plan, and validation evidence. No Learn link-validation job may fetch, import, vendor, or execute production code from netdata/seo, and Learn CI must not require an SEO checkout, workflow, artifact, service, or repository permission. SEO may consume published results for measurement, but it is never a production dependency.

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 Learn-owned weekly scheduled job, not by every pull request. Its issue and any repair pull request stay in this repository. Confirmation policy, issue lifecycle behavior, 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.

Static build gate contract

  • Learn commits the complete checksum-bound Node.js 22 gate under scripts/site-build-gate/ and runs it locally after Docusaurus. CI and deployment do not fetch or execute the SEO repository.
  • Learn declares /docs/collecting-metrics/collectors as its segment-safe integration route prefix. The generic page-weight diagnostic excludes that route family; integration pages remain subject to every non-weight rule, so this is not a whole-page validation bypass.
  • config/site-build-gate-baseline.json contains only exact, reasoned current findings. Never add or widen an entry to make a build pass without an explicit policy decision.

Generated Prometheus profile metrics

Agent-generated Prometheus profile coverage is rendered as ordinary tables grouped by each profile's top-level metric family. Learn identifies the exact generated table header only to apply responsive wrapping; it does not add search, disclosure, or other interactive catalogue behavior. Learn must not parse Agent profile source contracts or hand-edit generated integration pages.