fix: Content-based doc regeneration to eliminate empty PRs#790
Conversation
Replace the delete-all-and-regenerate approach with content-based comparison. For each command, docs are generated to a temp directory and compared with existing files (ignoring ms.date metadata). Files are only overwritten when real content changes are detected. Additional improvements: - Use deterministic GUIDs for TOC files (based on module name hash) instead of random GUIDs that change every run - Add orphan cleanup for docs whose commands are no longer in metadata - Build TOC content in memory and only write when changed - Auth module docs use the same comparison-based approach This reduces weekly PR diffs from ~25K files (every file touched) to only files with actual content updates, making PRs reviewable and staying within GitHub's diff rendering limits. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 7072409: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this comment.
Pull request overview
This PR updates the PowerShell reference-doc generation script to avoid “delete-and-regenerate everything” behavior, aiming to drastically reduce weekly automated PR sizes by only rewriting markdown files when meaningful content changes occur.
Changes:
- Generates cmdlet docs into temporary directories and only overwrites existing markdown when normalized content differs (ignoring
ms.date). - Makes module TOC GUIDs deterministic (hash-derived) and only writes TOC files when their content changes.
- Removes “orphaned” cmdlet markdown files no longer present in metadata.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Generate auth docs to temp directory, then compare | ||
| Set-Help -ModuleDocsPath $TempAuthDir -Command "Connect-MgGraph" -Module "Microsoft.Graph.Authentication" | ||
| $tempAuthFile = Join-Path $TempAuthDir $AuthPath "Connect-MgGraph.md" | ||
| $existingAuthFile = Join-Path $AuthDestination "Connect-MgGraph.md" | ||
| if ((Test-Path $tempAuthFile)) { | ||
| if (Test-Path $existingAuthFile) { | ||
| $existingContent = Get-NormalizedContent -FilePath $existingAuthFile | ||
| $newContent = Get-NormalizedContent -FilePath $tempAuthFile | ||
| if ($existingContent -ne $newContent) { | ||
| Copy-Item -Path $tempAuthFile -Destination $existingAuthFile -Force | ||
| Write-Host "Updated auth doc: Connect-MgGraph" | ||
| } else { | ||
| Write-Host "No content changes for auth doc: Connect-MgGraph" | ||
| } | ||
| } else { | ||
| if (-not (Test-Path $AuthDestination)) { | ||
| New-Item -Path $AuthDestination -ItemType Directory -Force | Out-Null | ||
| } | ||
| Copy-Item -Path $tempAuthFile -Destination $existingAuthFile -Force | ||
| Write-Host "Added auth doc: Connect-MgGraph" | ||
| } | ||
| } |
1. Auth module: generate and compare ALL auth cmdlet docs (not just Connect-MgGraph). Iterates all generated files in the temp auth module folder so other auth cmdlets stay current. 2. Get-NormalizedContent: normalize CRLF to LF and trim trailing whitespace before comparison, preventing false positives from line-ending differences between checkout and generated content. 3. Get-DeterministicGuid: explicitly cast hash slice to [byte[]] for unambiguous GUID constructor binding, and dispose SHA256 instance via try/finally to avoid resource leaks. 4. TOC comparison: normalize both existing and new TOC text to LF before comparing, preventing spurious rewrites from CRLF/LF mismatches on Windows checkouts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 0a0b22d: ✅ Validation status: passed
For more details, please refer to the build report. |
Problem
The weekly \powershell-docs.yml\ pipeline creates PRs with ~25,000+ changed files every run because \GenerateMarkDown.ps1\ deletes ALL existing docs and regenerates them from scratch. This produces diffs too large for GitHub to render (GitHub reports 0 changed files), making every weekly PR appear empty and unreviable.
Root Causes
Solution
Replace the delete-all approach with content-based comparison:
Impact