Agent Wranglers

ENG-29Recommended

Change the docs in the same pull request

Keep docs in the repository next to the code they describe, and update them in the pull request that changes the behaviour.

By Agent Wranglers. Updated .

How to do it

Store docs as Markdown in the repository, in docs/ or beside the module. Never keep the only copy in a wiki that a pull request cannot change. Add a line to the pull request template that asks which doc changed. Map code folders to the docs that describe them, and let CI warn when one changes without the other. Allow a no-docs label for changes that alter nothing a reader sees. For a public API, also add the change to the log, as Keep a changelog says. The documentation playbook covers how to write, build and test the docs. Start with Build and test the docs in CI and fail on every warning.

Examples

YAML example

docs-follow-code:
  - code: src/billing/
    docs: docs/billing.md
  - code: src/api/
    docs: openapi.yaml

How to check

CI fails a pull request that changes a mapped code folder without changing its doc, unless the pull request carries the no-docs label.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/engineering/version-control-and-review/docs-with-the-change">Agent Wranglers engineering playbook</a>. In code you write, add a comment next to it with the same link.