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 this site locally with
npm run buildfromsite/, then confirm/llms.txtand/llms-full.txtare served by the built output. - Review examples against the release tag.
Publishing automation
This page lives in the Docus site under site/, which deploys to Railway
and serves https://bloodraven.dev.
| Gate | Workflow | What it proves |
|---|---|---|
Pull requests and main pushes | .github/workflows/ci.yml | The site under site/ builds and llms-full.txt includes every page under site/content/docs/. |
| Release tags | .github/workflows/release.yml | The release candidate passes the same site build and llms-full.txt coverage check before images and charts publish. |
| Nightly and manual runs | .github/workflows/docs-link-check.yml | The public site under https://bloodraven.dev/ has no same-site broken links. |
Pushes to main touching site/ | .github/workflows/deploy-site.yml | The Docus site under site/ is uploaded to the Railway service bloodraven-site, which builds it and serves https://bloodraven.dev. |
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.