Self-Documenting PRs keep your Documents in lockstep with your code. When a pull request merges, Dosu checks the change against the published Documents in your Library, updates any that have drifted, and posts a summary you can act on without leaving the PR. This page explains what triggers a review, what Dosu does, and how your team stays in control.
What it is#
When you connect a code Source and turn on its Monitor, Dosu watches the repository for changes that affect your published knowledge. As a pull request moves through its life, Dosu:
- Reads the diff and finds the published Documents the change touches.
- Drafts targeted updates to the Documents that are now stale, with citations back to the PR, the code, and related discussion.
- Posts a single Knowledge review comment on the PR with each suggested update and clickable Accept, Edit, and Decline links.
- On merge, applies the accepted updates to your Library so the Documents reflect the merged code.
Dosu does not rewrite your repository files for Documents that live in your Library. It updates the published Documents in Dosu and summarizes the change on the PR. (For docs you imported from a repository, see Sync back, below.)
Why it matters#
Documentation rots the moment code ships. The person who made the change knows what changed, but writing the doc update is a separate chore in a separate tool, so it gets skipped. Across many repositories and a growing team, that gap compounds into onboarding drag, stale runbooks, and team knowledge that has not been documented.
Self-Documenting PRs close the gap where the work already happens. Documentation maintenance becomes a side effect of code merging rather than a backlog item. Your Library stays current as your codebase changes, which matters both for the people reading it and for the coding agents that pull context from it.
How it works#
What triggers a review#
Dosu runs a check when a pull request is opened, marked ready for review, or receives new commits. To avoid redundant runs on rapid pushes, Dosu waits about 10 minutes after the last commit before checking. Draft pull requests are ignored until they are marked ready for review. You can also trigger a check on demand by commenting /dosu-refresh on the PR.
What Dosu checks#
Dosu checks all published Documents in the Library against the PR, not only those Dosu generated. Drafts and unpublished Documents are not monitored, and changelog Documents are excluded from staleness checks. You can narrow the trigger with Monitored Paths so that only changes in specific directories trigger a check (the default is all paths).
The review comment#
The Knowledge review comment gives you a per-Document status table and a collapsible diff for each suggested update. Every suggestion carries three actions:
- Accept stages the update to publish when the PR merges.
- Edit lets you adjust the draft before accepting.
- Decline drops the suggestion.
Your decisions persist across new commits, so you do not re-review the same suggestion every time someone pushes. As you act, the links swap to a status badge in the comment so the thread stays readable.
On merge#
When the PR merges, Dosu publishes every accepted update (and any still pending, depending on your settings) to your Library. The merged PR is linked from the updated Document so the change is traceable. If the PR closes without merging, the staged updates are dropped.
Staying in control#
The Auto-Accept Review setting decides what happens to updates that were not explicitly actioned:
- On: updates publish automatically when the PR merges, so docs stay current with no manual step.
- Off: updates stay in review status and wait for someone to approve them before they are published.
You manage Monitor per Source and Auto-Accept Review per Library when you open or edit a Library at Libraries. Turning on a Source's Monitor is the prerequisite for Self-Documenting PRs to run on that repository.
Sync back to imported docs#
If you imported documentation that lives in a repository (for example, Markdown files on GitHub), accepted updates are pushed back to the repository. With Auto-Accept Review off, Dosu opens a sync pull request with the proposed changes and adds the author of the original PR as a reviewer, so the person who shipped the code reviews the matching doc update. Docs imported from a platform like Notion or Confluence are updated in place rather than through a pull request.
Notes and limits#
- A code Source must be connected, and its Monitor must be turned on.
- Only published Documents are checked. Publish a Document first if you want Dosu to keep it up to date.
- Changelog Documents are excluded from staleness checks.
- Generally available for GitHub today. Support for other code hosts is rolling out, so confirm your provider's availability before relying on it.
