A Monitor watches a Source for code changes that could affect your documentation and flags the Documents that may be going stale. This page explains what a Monitor is, when it runs, and what it sends to Review.
What it is#
When you add a Source to a Library, it has two switches: Read and Monitor.
- Read lets the Library reference that Source when answering questions and writing Documents.
- Monitor watches the Source for changes worth documenting and flags Documents that may be going stale.
A Monitor is the second switch. When code changes in a monitored Source, the Monitor reads each new pull request and issue, checks the change against your published Documents, and flags the ones that fall out of date with a suggested fix. When nothing needs updating, the Monitor stays quiet.
Monitors skip pull requests and merge requests from branches Dosu creates: dosu/doc-update-* and dosu/publish-*, including batch publishing. This applies on GitHub, GitLab, and Azure DevOps.
Monitors are how Dosu keeps documentation honest as the code moves. This is the knowledge-review and stale-docs capability: catch drift early, propose a fix, and let your team approve it.
Why it matters#
Documentation rots quietly. A function is renamed, a flag is removed, an endpoint changes shape, and the page that described it is now wrong. Across many repositories and teams this is the default, and the people who knew the old context have often moved on.
A Monitor turns documentation maintenance into a side effect of normal development instead of a separate chore nobody owns. Drift gets flagged on the pull request that caused it, before the change merges. That keeps a shared source of truth current as your organization grows, and it cuts the cost of feeding coding agents stale context.
How it works#
A Monitor runs against the published Documents in a Library. The steps below describe the default On open and merge option of the Source's When to Review Changes setting.
- A pull request (or merge request) is opened or marked ready for review in a monitored Source. Draft pull requests are ignored until they are ready.
- The Monitor compares the code changes against published Documents that reference the affected code.
- For each Document, it decides whether the Document is still valid, needs an update, or no longer applies.
- For anything that looks stale, it drafts a targeted edit and sends it to Review.
With the default option, the Monitor checks the pull request again when it merges.
What a Monitor produces#
When a Monitor flags a Document, your team reviews the proposal in one of two places:
- An in-PR or in-MR review comment with Accept, Edit, and Decline actions, so you can resolve drift without leaving the pull request.
- The Review page, where the same drafts are listed for approval or editing.
When a Monitor reviews a change and finds nothing to update, you choose how it signals that. It can react with an emoji, post a short comment, or stay silent.
Azure DevOps pull requests do not support reactions, so the emoji up-to-date behavior posts a comment instead. New Azure DevOps Monitors save comment, and the CLI (libraries monitors list / update) reports a saved emoji on Azure DevOps as comment. The Monitor settings for an Azure DevOps Source do not offer React with š, and they show a saved emoji as Post a comment.
Your decisions carry over across later commits on the same pull request, so you do not re-review the same proposal twice. See Review and Knowledge Reviews for how approval works.
Scope and requirements#
You can narrow what a Monitor watches with Monitored Paths, a set of glob patterns (for example src/** or docs/**). The default is to watch all paths. Use a narrower set to focus on the directories that map to your Documents and skip build or test files. You manage this on the Source inside its Library.
For a Monitor to flag a Document, three things must be true:
- The Document is published. Drafts and pending Documents are not watched.
- The tool is connected as a Source with Monitor turned on.
- The Library is set up to review changes (on by default).
An edit you accept while its GitHub pull request is open publishes when the pull request merges. The Library's Auto Accept Review setting applies only to edits nobody has acted on. When it is on, Dosu accepts them automatically. When it is off, they wait in Review until someone accepts them.
When Dosu commits a documentation update directly to a pull request's branch using Commit to Source PR, merging that pull request does not trigger a fresh documentation review. This avoids redrafting updates already committed. Pending topic-page updates are still accepted at merge. Other pending updates are accepted when Auto Accept Review is on and remain in Review when it is off.
Turning a Monitor on#
You manage Monitors on a Source inside a Library. Open or create a Library at Libraries, add or open a Source, and turn Monitor on. From there you set when the Monitor reviews changes, how it reacts to them, and which paths trigger documentation updates.
When to review changes#
The When to Review Changes setting on a Source's Monitor tab controls which pull request or merge request events start a check. You can also set it while you add Sources to a new Library.
- With On open and merge, the default, the Monitor checks a pull request when it is opened or marked ready for review, and again when it merges.
- With On merge only, the Monitor checks each pull request once, after it merges, instead of while it is still changing.
Each Library keeps its own setting for a Source, so two Libraries that monitor the same repository can review on different events.
Availability#
Monitor is available for GitHub, GitLab, and Azure DevOps Sources. See Sources and the GitHub integration for connector details.