Skip to main content
A PR should be reviewable from first principles. Reviewers should be able to answer “what changed?” and “how do we know it works?” without relying on out-of-band context.

​
Required in the PR description

  • What changed (1–3 bullets)
  • Why (motivation / problem)
  • Verification steps (commands, tests)
  • Docs/spec impact:
    • OpenAPI changed? (yes/no)
    • Protobuf events changed? (yes/no)
    • Docs pages updated? (links)

​
Documentation expectations

If a change affects:
  • End users: update Customer Docs.
  • Integrators: update Developer Guide and/or API Reference.
  • Operators: update Enterprise or Internal runbooks.
If a PR changes runtime behavior and does not update docs (or explicitly justify why not), it is incomplete.

​
Suggested verification format

  • Service tests/checks (see service Makefile / README.md)
  • A concrete example request if an endpoint changed
  • python3 scripts/sync_reference.py --check (from platform/atlas) if contracts or schemas changed