Maintenance
Docs Maintenance
Use this page before releases and when changing CRDs, Helm values, metrics, dashboards, Events, or logs.
Use this page before releases and when changing CRDs, Helm values, metrics, dashboards, Events, or logs.
Ownership
| Area | Owner |
|---|---|
| Platform install and chart docs | Platform team |
| CRD reference and behavior docs | Operator maintainers |
| Backup and restore docs | Database/infra team |
| App integration docs | Application platform team |
| Security model | Security and operator maintainers |
| Runbooks | On-call owners |
Standard task page structure
- Overview.
- Prerequisites.
- Example manifest or command.
- Apply.
- Verify.
- Troubleshoot.
- Next steps.
Standard reference page structure
- What this page covers.
- Concepts.
- Field or behavior reference.
- Examples.
- Failure modes.
- Related pages.
Terminology
Use these terms consistently:
| Preferred | Avoid |
|---|---|
| primary | master |
| replica | slave |
| site | datacenter unless specifically referring to a datacenter |
| active site | current writable site |
| standby site or replica site | passive promotion candidate |
| dr-only site | passive site that is never auto-promoted |
| failover group | cluster, unless discussing Kubernetes clusters |
Example names
| Item | Default example |
|---|---|
| Failover group | orders |
| Namespace | orders |
| Sites | iad, pdx |
| DNS name | orders.az.example.com |
| Operator namespace | bloodraven |
| StorageClass | fast-ssd |
Release checklist
- Regenerate API docs if fields changed.
- Check Helm values references.
- Check dashboard list and UIDs.
- Check metrics list and alert names.
- Check Event and log schema docs.
- Check upgrade policy.
- Check known limitations.
- Build docs locally with
npm run buildfromdocs/. - Verify
llms-full.txtwithnpm run verify:llmsfromdocs/. - Review examples against the release tag.
Publishing automation
GitHub Actions treats the documentation site as a release artifact:
| Gate | Workflow | What it proves |
|---|---|---|
Pull requests and main pushes | .github/workflows/ci.yml | Docusaurus builds and llms-full.txt includes every page under docs/docs/. |
| Release tags | .github/workflows/release.yml | The release candidate passes the same docs build and llms-full.txt coverage check before images and charts publish. |
main pushes | ReadTheDocs project setting | ReadTheDocs watches the repository and publishes the latest version from the merged commit. |
| Nightly and manual runs | .github/workflows/docs-link-check.yml | The public site under https://bloodraven.dev/ has no same-site broken links. |
Keep the ReadTheDocs project connected to the repository so merged changes publish without a GitHub Actions token or custom API trigger.
Validation checklist
- YAML examples use
shipstream.io/v1alpha1. - Required CRD fields are present.
- Deprecated fields are labelled as deprecated.
- Command blocks use explicit namespaces.
- Example passwords are clearly placeholders.
- Helm values match
charts/bloodraven/values.yaml. - Internal links build cleanly.