Docs per release policy

This page is the canonical reference for Docs per release policy.

Who this is for

• Maintainers preparing a release
• Reviewers validating that a change is “customer-ready”

What you will get

• A checklist that turns doc updates into a release habit (not an afterthought)
• Clear “when X changes, update Y” guidance for the suite docs site

Policy

• Doc changes ship with product changes.
• The canonical API spec lives in OpenAPI spec (YAML).
• Tutorials must remain runnable (see the tutorial smoke test workflow).

Checklists (by change type)

HTTP API changes

• Update docs/reference/api/openapi.yaml.
• Regenerate derived API artifacts: cd api && make codegen.
• Update examples and troubleshooting pages if behavior changed:
• API examples (HTTP files)
• Error handling & troubleshooting API calls
• Add an entry to “What’s new” for customer-visible changes:
• What’s new

Config changes

• Update the config reference:
• Configuration reference
• module-specific pages under reference/config/
• If a setting changes defaults or semantics, add a note to “What’s new”.

Data contract changes (exposures/outcomes/manifests)

• Update:
• Data contracts
• schema files under reference/data-contracts/ (and examples)
• Update join/explanation docs if attribution logic changes:
• Event join logic (exposures ↔ outcomes ↔ assignments)
• Exposure logging and attribution

Operational behavior changes

• Update runbooks for new failure modes or changes in remediation:
• docs/operations/runbooks/*
• Update capacity guidance if perf characteristics changed:
• Performance and capacity guide

Verification (required)

Run the suite-level quality gates:

make finalize

If you changed tutorials or serving behavior, also run the tutorial smoke test locally (or wait for CI):

bash scripts/tutorial_smoke_test.sh

Read next

• Docs versioning: Docs versioning