Add PowerShell script to add review comments on PRs modifying release notes (#2058)

### ❔What, Why & How

Contributors updating `RELEASENOTES.md` need to be notified when a new
AL-Go version is released so they can move their changes above the new
version section to maintain proper changelog structure.

**Solution:**

- **PowerShell Script**
(`Internal/Scripts/CommentOnExistingReleaseNotesPrs.ps1`): Manual script
using GitHub CLI to add review comments directly on RELEASENOTES.md file
changes in open PRs
- **Automatic Version Detection**: Script automatically detects the
current version from `RELEASENOTES.md` using multiline regex pattern
that supports vX.Y format only
- **Inline Documentation**: Complete usage instructions and
implementation details in the script header

**Usage:**

```powershell
# Recommended: Use gh auth login for secure authentication
gh auth login

# Or set token as environment variable (may be visible in shell history)
$env:GH_TOKEN = "your-token-here"
# or
$env:GITHUB_TOKEN = "your-token-here"

# Run the script
pwsh Internal/Scripts/CommentOnExistingReleaseNotesPrs.ps1
```

**Key Features:**
- **GitHub CLI Integration**: Uses `gh` commands for better readability
and maintainability
- **Review Comments on File Changes**: Adds comments directly on
RELEASENOTES.md file in the "Files changed" tab at line 1, not as
general PR comments
- **Version Release Notification**: Informs contributors that a new
AL-Go version has been released and their changes need to be moved
- **Automatic Version Detection**: No manual updates needed when
releasing new versions (supports vX.Y format only)
- **Fail-fast Error Handling**: Errors out if version cannot be detected
(no fallback defaults)
- **Version-Specific Comment Checking**: Verifies if review comments for
the current version exist on RELEASENOTES.md before adding new ones,
allowing re-commenting when version changes
- **Comprehensive Reporting**: Detailed summary with success/skip/fail
counts and failed PR list
- **Robust Error Handling**: Handles edge cases (empty PR lists, null
results, API failures) with proper array checking
- **Secure Authentication**: Recommends `gh auth login` with warnings
about shell history exposure
- **Resource Cleanup**: Finally block ensures temporary files are always
removed
- **Exit Codes**: Returns 0 for success, 1 for failures
- **Idiomatic PowerShell**: Uses `@()` array operator for clean, simple
array handling
- **Self-Documenting**: All documentation is in the script header for
easy maintenance
- **Code Quality**: UTF-8 with BOM encoding, passes all pre-commit
checks and PSScriptAnalyzer validation with zero alerts
- **Scalability**: Supports up to 1000 open PRs (maximum limit for gh
CLI)
- **Progress Suppression**: Includes `$ProgressPreference =
"SilentlyContinue"` for cleaner output in automated scenarios
- **Naming Convention**: Script follows PascalCase naming convention
consistent with other PowerShell scripts in the repository

**Comment Message:**
```
A new version of AL-Go (vX.Y) has been released.

Please move your release notes changes to above the ## vX.Y section in the RELEASENOTES.md file.

This ensures your changes are included in the next release rather than being listed under an already-released version.
```

**Implementation Details:**
- Uses multiline regex `(?m)^##\s*v(\d+\.\d+)` for version detection
(major.minor format only)
- Creates review comments using GitHub API endpoint
`/repos/{owner}/{repo}/pulls/{pr}/comments` with required `line: 1`
field
- Review comments include `path: "RELEASENOTES.md"`, `line: 1`, and the
PR's head commit SHA
- Checks for existing review comments on RELEASENOTES.md file with
version-specific text: "A new version of AL-Go (vX.Y) has been
released."
- Version-specific checking prevents false positives from comments about
different versions and allows re-commenting when a new version is
released
- Properly validates empty arrays using
`@($existingReviewComments).Count -gt 0` check
- Uses `Write-Host` with error indicators (✗) for consistent error
reporting instead of `Write-Warning`
- Tracks success, skip, and fail counts separately
- Lists specific PR numbers that failed for manual review
- Uses `@()` array operator for simplified null-safe array handling
- Properly escapes `$searchText` to prevent issues with special
characters in jq filters
- Fetches up to 1000 open PRs (maximum for gh CLI) with documentation
note about limitation
- Suppresses progress bars with `$ProgressPreference =
"SilentlyContinue"` for consistency with other scripts in the repository
- Discards API response output using `Out-Null` to avoid unused variable
warnings
- Script is located in `Internal/Scripts/` alongside other internal
utility scripts
- File encoded with UTF-8 with BOM for PSScriptAnalyzer compliance
- Code follows repository standards with no trailing whitespace
- File name uses PascalCase (`CommentOnExistingReleaseNotesPrs.ps1`) to
match repository conventions (e.g., `GetOwnerForE2ETests.ps1`,
`RemoveTempRepos.ps1`)

**Requirements:**
- GitHub CLI (`gh`) installed: https://cli.github.com/
- GitHub authentication (via `gh auth login` or token)
- PowerShell 7 or later

Related to issue: #

### ✅ Checklist

- [ ] Add tests (E2E, unit tests)
- [ ] Update RELEASENOTES.md
- [x] Update documentation (e.g. for new settings or scenarios)
- [ ] Add telemetry

<!-- START COPILOT CODING AGENT SUFFIX -->



<details>

<summary>Original prompt</summary>

> Go through all open PRs that change the release notes and add a
comment that it needs to be moved above the new version section.


</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mazhelez <43066499+mazhelez@users.noreply.github.com>

Author: Copilot

Internal/Scripts/CommentOnExistingReleaseNotesPrs.ps1

@@ -0,0 +1,225 @@
+#!/usr/bin/env pwsh
+
+<#
+.SYNOPSIS
+    Adds a comment to all open PRs that modify RELEASENOTES.md
+.DESCRIPTION
+    This script searches for all open PRs that have changes to RELEASENOTES.md
+    and adds a reminder comment about placing changes above the new version section.
+
+    Uses GitHub CLI (gh) for better readability and maintainability.
+
+    The script will:
+    1. Verify GitHub CLI is installed and authenticated
+    2. Automatically detect the current version from RELEASENOTES.md
+    3. Fetch all open pull requests using 'gh pr list'
+    4. Check each PR to see if it modifies RELEASENOTES.md
+    5. For PRs that modify the release notes:
+       - Check if an active reminder comment already exists
+       - If not, add a comment reminding contributors to place changes above the new version section
+    6. Provide a detailed summary with success/skip/fail counts
+    7. List any PRs where comment addition failed
+.PARAMETER Owner
+    The repository owner (default: microsoft)
+.PARAMETER Repo
+    The repository name (default: AL-Go)
+.EXAMPLE
+    # Recommended: Use gh auth login (more secure)
+    gh auth login
+    ./comment-on-existing-release-notes-prs.ps1
+.EXAMPLE
+    # Alternative: Set GH_TOKEN or GITHUB_TOKEN environment variable
+    # Note: Tokens may be visible in shell history
+    $env:GH_TOKEN = "your-token-here"
+    ./comment-on-existing-release-notes-prs.ps1
+.NOTES
+    Requirements:
+    - GitHub CLI (gh) installed: https://cli.github.com/
+    - GitHub authentication (via 'gh auth login' or GH_TOKEN/GITHUB_TOKEN environment variable)
+    - PowerShell 7 or later
+
+    Error Handling:
+    - Errors out if GitHub CLI is not installed
+    - Errors out if not authenticated
+    - Errors out if version cannot be detected from RELEASENOTES.md
+    - Tracks and reports failed comment additions
+    - Exit code 1 if any comments fail, 0 if all successful
+#>
+
+param(
+    [string]$Owner = "microsoft",
+    [string]$Repo = "AL-Go"
+)
+
+$ErrorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0
+
+# Check if gh CLI is available
+if (-not (Get-Command gh -ErrorAction SilentlyContinue)) {
+    Write-Error "GitHub CLI (gh) is not installed. Please install it from https://cli.github.com/"
+    exit 1
+}
+
+# Verify authentication
+try {
+    $null = gh auth status 2>&1
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "GitHub CLI is not authenticated. Run 'gh auth login' or set GH_TOKEN/GITHUB_TOKEN environment variable."
+        exit 1
+    }
+} catch {
+    Write-Error "Failed to verify GitHub CLI authentication: $_"
+    exit 1
+}
+
+# Detect current version from RELEASENOTES.md
+$releaseNotesPath = Join-Path $PSScriptRoot "../../RELEASENOTES.md"
+if (-not (Test-Path $releaseNotesPath)) {
+    Write-Error "RELEASENOTES.md not found at $releaseNotesPath"
+    exit 1
+}
+
+$releaseNotesContent = Get-Content -Path $releaseNotesPath -Raw
+if ($releaseNotesContent -match '(?m)^##\s*v(\d+\.\d+)') {
+    $currentVersion = "v$($matches[1])"
+    Write-Host "Detected current version: $currentVersion"
+} else {
+    Write-Error "Could not detect version from RELEASENOTES.md. Expected to find a line matching '## vX.Y'"
+    exit 1
+}
+
+$comment = @"
+A new version of AL-Go ($currentVersion) has been released.
+
+Please move your release notes changes to above the ``## $currentVersion`` section in the RELEASENOTES.md file.
+
+This ensures your changes are included in the next release rather than being listed under an already-released version.
+"@
+
+Write-Host "Fetching open pull requests for $Owner/$Repo..."
+
+# Get all open PRs using gh CLI
+# NOTE: The maximum limit for 'gh pr list' is 1000. If the repository has more than 1000 open PRs, some may be missed.
+$prsJsonOutput = gh pr list --repo "$Owner/$Repo" --state open --limit 1000 --json number,title,files
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Failed to fetch pull requests from GitHub"
+    exit 1
+}
+
+$prsJson = @($prsJsonOutput | ConvertFrom-Json)
+
+Write-Host "Found $($prsJson.Count) open PRs. Checking which ones modify RELEASENOTES.md..."
+
+$prsWithReleaseNotes = @()
+
+foreach ($pr in $prsJson) {
+    $prNumber = $pr.number
+    Write-Host "Checking PR #$prNumber..."
+
+    # Check if RELEASENOTES.md was modified
+    $releaseNotesModified = $pr.files | Where-Object { $_.path -eq "RELEASENOTES.md" }
+
+    if ($releaseNotesModified) {
+        Write-Host "  ✓ PR #$prNumber modifies RELEASENOTES.md"
+        $prsWithReleaseNotes += $pr
+    } else {
+        Write-Host "  - PR #$prNumber does not modify RELEASENOTES.md"
+    }
+}
+
+if ($prsWithReleaseNotes.Count -eq 0) {
+    Write-Host "`nNo PRs found that modify RELEASENOTES.md. Exiting."
+    exit 0
+}
+
+Write-Host "`nFound $($prsWithReleaseNotes.Count) PRs that modify RELEASENOTES.md"
+Write-Host "`nAdding comments to PRs..."
+
+$successCount = 0
+$skipCount = 0
+$failCount = 0
+$failedPRs = @()
+
+foreach ($pr in $prsWithReleaseNotes) {
+    $prNumber = $pr.number
+    $prTitle = $pr.title
+
+    Write-Host "`nProcessing PR #${prNumber}: $prTitle"
+
+    # Check if we've already commented (check for review comments on RELEASENOTES.md)
+    $searchText = "A new version of AL-Go ($currentVersion) has been released."
+    $escapedSearchText = $searchText -replace '\\', '\\\\' -replace '"', '\"'
+    $existingReviewCommentsOutput = gh api "/repos/$Owner/$Repo/pulls/$prNumber/comments" --jq "[.[] | select(.path == `"RELEASENOTES.md`" and (.body | contains(`"$escapedSearchText`")))]"
+
+    if ($LASTEXITCODE -eq 0) {
+        $existingReviewComments = $existingReviewCommentsOutput | ConvertFrom-Json -ErrorAction SilentlyContinue
+
+        if ($existingReviewComments -and @($existingReviewComments).Count -gt 0) {
+            Write-Host "  ℹ️  Review comment already exists on RELEASENOTES.md in PR #$prNumber, skipping..."
+            $skipCount++
+            continue
+        }
+    }
+
+    # Add review comment on RELEASENOTES.md file
+    $tempFile = $null
+    try {
+        # Get the commit SHA for the PR
+        $prDetails = gh api "/repos/$Owner/$Repo/pulls/$prNumber" | ConvertFrom-Json
+        $commitSha = $prDetails.head.sha
+
+        # Create review comment payload
+        $reviewCommentBody = @{
+            body = $comment
+            path = "RELEASENOTES.md"
+            commit_id = $commitSha
+            line = 1
+        } | ConvertTo-Json -Compress
+
+        # Save to temp file
+        $tempFile = [System.IO.Path]::GetTempFileName()
+        Set-Content -Path $tempFile -Value $reviewCommentBody -NoNewline
+
+        # Post the review comment
+        gh api -X POST "/repos/$Owner/$Repo/pulls/$prNumber/comments" --input $tempFile | Out-Null
+
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  ✓ Review comment added to RELEASENOTES.md in PR #$prNumber"
+            $successCount++
+        } else {
+            Write-Host "  ✗ Failed to add review comment to PR #${prNumber}"
+            $failCount++
+            $failedPRs += $prNumber
+        }
+    }
+    catch {
+        Write-Host "  ✗ Failed to add review comment to PR #${prNumber}: $_"
+        $failCount++
+        $failedPRs += $prNumber
+    }
+    finally {
+        # Always clean up temp file
+        if ($tempFile -and (Test-Path $tempFile)) {
+            Remove-Item -Path $tempFile -Force -ErrorAction SilentlyContinue
+        }
+    }
+}
+
+# Final summary
+Write-Host "`n========================================="
+Write-Host "Summary:"
+Write-Host "  Total PRs with RELEASENOTES.md changes: $($prsWithReleaseNotes.Count)"
+Write-Host "  Comments added: $successCount"
+Write-Host "  Skipped (already commented): $skipCount"
+Write-Host "  Failed: $failCount"
+
+if ($failCount -gt 0) {
+    Write-Host "`n⚠️  Failed to add comments to the following PRs:"
+    foreach ($prNum in $failedPRs) {
+        Write-Host "  - PR #$prNum"
+    }
+    Write-Host "`nPlease review these PRs manually."
+    exit 1
+} else {
+    Write-Host "`n✓ Done! All comments have been processed successfully."
+    exit 0
+}