docs / adoption

Adoption: assist → warn → enforce

The safest way to introduce a convention is to roll it out gradually: help first, make unresolved points visible next, then decide together whether — and how — to enforce it. Assist and warn work today through the extension alone. Enforce, as an authoritative, platform-level requirement, is still on the roadmap — see the Enforce roadmap for that part.

The rollout sequence

week 0–2assistInstall the extension and let people use it. No status is published anywhere. Nothing is measured centrally, unless your organization has explicitly enabled telemetry.

week 2–6warnUnresolved blocking points become visible directly on the pull request without rejecting comments or blocking merges.

laterenforceNot available yet as an authoritative, platform-level requirement. Track the roadmap for GitHub, Azure DevOps, and other platforms.

Mode	What the extension does	Effect on the pull request
off	Does nothing.	None.
assist	Helps reviewers write compliant comments and reports diagnostics. Never blocks.	None.
warn	Same as `assist`, plus a visible count of unresolved blocking threads.	Visible, never blocking.
enforce	Can refuse to submit a malformed comment locally, in the browser.	There is no authoritative platform-level merge gate yet; that capability is still on the roadmap.

Because these stages currently depend only on the extension, moving between them is just a configuration change. There is no separate infrastructure to deploy, restart, or remove.

One prerequisite worth setting early

Configure resolverOverrideGroup before relying on decision replies to close out blocking threads. This defines who may record a decision when the original author of a blocking comment is unavailable. Left empty, nobody can use that escape hatch, and a blocking thread can get stuck with no way to close it.

Rolling back

Every stage here is a single mode change in your configuration, applied through the same three-level system described in configuration. Moving back from warn to assist, or from enforce's local strict mode to warn, takes effect the next time the extension reads the configuration — there's no separate service to restart or branch-protection setting to unwind, because none of these stages touch your platform's own merge rules yet.

What to watch before going further

There's no organization-wide dashboard today — that kind of aggregate reporting is part of what an authoritative, platform-level check would eventually enable. In the meantime, what's worth watching is qualitative: are reviewers finding the right labels, are blocking threads getting resolved instead of stalling, and does the warn-stage count on a pull request usually reach zero before it merges. Uneven label use or blocking counts that never quite hit zero are both signals to slow down rather than push toward stricter enforcement.

Configuration for each stage

Only one setting needs to change as you move from one stage to the next: mode. Everything else should already be in place.

{
  "version": 1,
  "mode": "warn",                    // assist → warn → enforce
  "resolverOverrideGroup": ["acme/tech-leads"],
  "formatSeverity": "warn",          // formatting issues do not block
  "exemptUsers": ["dependabot[bot]", "github-actions[bot]"],
  "toolCommands": ["/*", "@dependabot", "@renovate"]
}

worth checking before you enable it

toolCommands is empty by default. In enforce's local strict mode, a bare /rebase is rejected like any other non-compliant comment unless it has been declared. Adding "/*" exempts all slash commands.