Skip to main content

Source: docs/manual/docs-governance.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Docs Governance and Versioning

Purpose​

This policy defines how Cruvero documentation is authored, generated, reviewed, and versioned so the docs site stays accurate as runtime features evolve.

Source of Truth​

  • Runtime and API behavior: Go source in cmd/** and internal/**
  • Operator and developer reference content: docs/manual/**
  • Published docs site content: site/docs/** and site/src/pages/**
  • Generated OpenAPI reference artifact: site/static/api/openapi.json (digest tracked by site/static/api/openapi.sha256)

Ownership​

  • Global docs ownership is enforced through .github/CODEOWNERS.
  • Pull requests touching docs paths must include owner review before merge.

Authoring Standards​

All docs pages in site/docs/** and site/src/pages/** must include frontmatter with:

  • title
  • description
  • source_path

Rules:

  • Avoid legacy Hugo frontmatter fields such as weight.
  • Keep headings shallow (h2/h3) unless deeper structure is required.
  • Prefer runnable command examples where applicable.
  • Use stable links (site routes or absolute repository links).

Generated Content Policy​

The manual-to-site sync is deterministic and script-driven:

  • Generator: site/scripts/sync-manual-docs.mjs
  • Audit: site/scripts/content-audit.mjs
  • Built-link validation: site/scripts/check-built-links.mjs

When source manual docs change, regenerate and commit updated site docs in the same PR.

OpenAPI Drift Policy​

OpenAPI freshness is guarded by a checksum file:

  1. Generate spec: make site-openapi
  2. Update digest: site/scripts/openapi-sha.sh update
  3. Commit site/static/api/openapi.sha256

CI verifies the digest using site/scripts/openapi-sha.sh check.

Versioning Strategy​

  • Current mode: unversioned latest docs on the docs site.
  • Near-term policy: create version snapshots at runtime minor releases once API/CLI churn stabilizes.
  • Every release snapshot must include:
    • API reference
    • CLI reference
    • configuration reference
    • migration and operational notes

Release Checklist for Docs​

Before merge:

  1. Run docs sync and audit checks.
  2. Build the site with broken-link checks enabled.
  3. Validate generated OpenAPI digest.
  4. Confirm critical routes render (/, /getting-started, /develop, /operations, /api, /architecture).

Future-Proofing​

  • Keep generated docs scripts idempotent and deterministic.
  • Prefer metadata-backed validation (source_path, digest files) over manual spot checks.
  • Add additional generated references (CLI/config extraction) through scripts rather than manual duplication.