Documentation maintenance
Documentation is maintained with the same review discipline as source code. Pull requests run the deterministic checks; a scheduled workflow checks external sites without making transient network failures block ordinary contributions.
Quality gates
| Check | Local solution build | Pull requests | Scheduled | Failure policy |
|---|---|---|---|---|
| Markdown structure and formatting | Required | Required | No | Any violation fails |
| Executable snippet synchronization | Required | Required | No | Any stale snippet fails |
| Internal files and anchors | Required | Required | Yes | Any missing target fails |
| XML comments and generated API pages | Required | Required | No | Any selected Docfx warning fails |
| External links | No | No | Weekly and manual | Permanent failures fail; transient failures warn after retries |
An ordinary local solution build runs the pull-request-equivalent checks once, after its library
projects finish. During a source-only iteration, pass -p:VerifyDocumentationOnBuild=false to opt
out temporarily. Run an ordinary build again before opening a pull request.
Markdown and link checks exclude Git-ignored working files under .codex/plans/. Keep user-facing
guides under docs/ so they participate in the documentation gates and generated site.
To run the documentation gate directly after a Release build:
./eng/verify-documentation.ps1 -NoBuild -WarningsAsErrors
Run the broader external check when changing destinations or preparing a release:
./eng/verify-documentation-links.ps1 -CheckExternalLinks -TransientFailurePolicy Warn
External 404 and 410 responses, and other non-transient client errors, fail immediately.
Timeouts, rate limits, and server errors are retried with bounded backoff. They become warnings by
default because a third-party outage is not evidence that repository content is wrong. Pass
-TransientFailurePolicy Error during a deliberate strict audit.
The project's own GitHub Pages URLs are excluded from network probing because the same workflow validates those generated paths locally before deployment. Every excluded pattern must include a documented reason here and remain as narrow as possible.
Review schedule
| Area | Responsible reviewers | Cadence | Additional trigger | Last full review | Next review by |
|---|---|---|---|---|---|
| Entry points and package selection | Repository maintainers | Quarterly | Package added, renamed, or split | 2026-09-27 | 2026-12-31 |
| Core hosts, authentication, and scenarios | Core-package maintainers | Quarterly | Public hosting or authentication change | 2026-09-30 | 2026-12-31 |
| HTTP, messaging, Azure, and observability boundaries | Owning package maintainers | Quarterly | New matcher, transport, collector, or SDK helper | 2026-09-29 | 2026-12-31 |
| Testcontainers, Aspire, and Azure Functions | Infrastructure maintainers | Quarterly | Runtime, image, trigger, or framework support change | 2026-09-27 | 2026-12-31 |
| Snapshot workflows and safety guidance | Snapshot maintainers | Every release | Update, redaction, naming, or package change | 2026-10-05 | Next release |
| API reference and package landing pages | Public-API owner | Every release | Public API approval changes | 2026-10-05 | Next release |
| Security, limitations, and migration guidance | Release maintainer | Every release | Security or breaking behavior change | 2026-10-01 | Next release |
The Azure Functions factory guide, factory API comments, and API navigation were reviewed on 2026-10-21 for startup and disposal boundaries, failure modes, guide links, package selection, and search.
The Durable context defaults, fluent overrides, orchestration recipes, snapshot assertion options, and their API approvals and upgrade guidance were reviewed on 2026-10-22 for the 1.3.0 release.
The Durable client, entity, connected workflow, retry, and serialization guides and API approvals were reviewed on 2026-10-23, together with JSON string line-ending normalization and package entry points. The coverage inventory includes these features and their executable tests.
A review confirms examples still compile, defaults and limitations remain accurate, external requirements are current, links reach the intended material, and sensitive-data guidance matches the implementation. Update the dates in this table in the pull request that records a full review.
Coverage ownership
Every public feature belongs in docs/contributing/documentation-coverage.md. A public behavior change must do
one of the following:
- Update the existing feature or package row and its canonical documentation.
- Add a row for a new capability and identify the milestone or maintenance owner.
- State in the pull-request summary why the change has no user-facing documentation impact.
Do not mark an area Detailed merely because an API page exists. Detailed coverage also requires a
task-oriented path, realistic example, limitations, diagnostics, and related API links.