Optimize PR validation for XML documentation changes

[Amaury Levé (Evangelink)]

PRs that change only C# XML documentation currently run the full multi-OS build and test matrix even though their meaningful compiler input is limited to generated documentation. PR #10740 is a representative example.

Approach

• Add a fail-closed Roslyn classifier that verifies every changed file is an existing non-sample C# file and that code, directives, strings, and ordinary comments are unchanged.
• Extract and execute the classifier from the trusted PR target branch, never from the contribution being classified. A missing or failing trusted classifier selects full validation.
• Route eligible product XML-documentation-only changes through the Windows Release build/package lane without tests.
• Retain full validation for sample changes and XML <include> documentation because their build coverage and path semantics can be platform-sensitive.
• Fall back to full validation for mixed changes, parse errors, unsupported syntax, file additions or deletions, classifier failures, or unexpected output.

The target branch does not contain the classifier until this PR merges, so this PR intentionally exercises the full validation matrix. Subsequent PRs can use the optimized path from the trusted merged version.

Validation

• PowerShell classifier self-tests, including raw strings, mixed comments, directive relocation, XML includes, and sample paths
• End-to-end temporary Git repository tests for multi-file documentation, mixed code, added files, and deleted files
• Copied-script execution with an explicit repository path, matching target-branch extraction in CI
• Historical PR classification: Document IDataConsumer UID filtering #10740 and Clarify DeploymentItemAttribute XML doc comments #8968 accepted; Clarify XML docs for TestContext result/deployment directories #9180 rejected because it also changes an ordinary comment
• PowerShell Script Analyzer
• Azure Pipelines YAML parsing
• Existing affected-test pipeline validation

[Copilot]

Pull request overview

Optimizes validation for XML-documentation-only C# changes by classifying diffs and reducing CI execution.

Changes:

• Adds a fail-closed Roslyn-based PowerShell classifier.
• Routes documentation-only changes through Release build lanes while skipping tests and multi-OS jobs.

Show a summary per file

File	Description
eng/classify-xml-doc-change.ps1	Classifies XML-documentation-only diffs.
azure-pipelines.yml	Uses classification to reduce validation jobs.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Note

🤖 Automated review by GitHub Copilot. Generated by the Expert Code Review workflow. To request a follow-up action, reply by tagging @copilot directly.

#	Dimension	Verdict
13	Test Completeness & Coverage	🟢 1 NIT
17	Documentation Accuracy	🟢 1 NIT
20	Build Infrastructure & Dependencies	🟡 1 MODERATE

✅ 19/22 dimensions clean. 3 dimensions N/A (Analyzer Quality, IPC Wire Compatibility, MSBuild Authoring — no relevant files changed).

Summary: Well-designed fail-closed classifier with good self-tests and correct pipeline condition logic. The Roslyn assembly loading is implicit (relying on agent environment), but the bash wrapper's if ! guard ensures graceful degradation. The pipeline conditions correctly route xmlDocsOnly PRs through minimal validation while preserving full validation for any ambiguity.

• Build Infrastructure — Roslyn assembly loading is implicit; consider explicit load with clear error
• Test Completeness — self-tests could cover removed-doc and preprocessor-directive cases
• Documentation — Release lane comment could clarify "validation" means compilation only (tests skipped)

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

eng/classify-xml-doc-change.ps1:272

• The self-tests are not executed by any repository pipeline invocation: the only call site invokes this script with -Base/-Head. As a result, regressions in this safety-critical classifier (including the raw-string and mixed-comment cases) will not fail CI. Add a -SelfTest step to DetectChanges before using the classifier result.

if ($SelfTest) {
    Invoke-SelfTest
    exit 0

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

eng/classify-xml-doc-change.ps1:144

• This explicitly rejects every sample C# file, so xmlDocsOnly is false for sample documentation-only PRs and WindowsSamples still runs both Release and Debug (along with the normal Debug lane). That contradicts the PR description's stated routing of sample XML-documentation-only changes through only the WindowsSamples Release lane. If retaining full validation for samples is intentional, update the PR description to remove that claimed optimization; otherwise sample classification and matrix gating still need to be implemented.

        -not $Path.StartsWith("samples/", [System.StringComparison]::Ordinal))

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Balanced