Convert breaking-change-doc workflow to GitHub agentic workflow

.github/aw/actions-lock.json

@@ -5,6 +5,11 @@
       "version": "v8",
       "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
     },
+    "actions/upload-artifact@v4": {
+      "repo": "actions/upload-artifact",
+      "version": "v4",
+      "sha": "ea165f8d65b6e75b540449e92b4886f43607fa02"
+    },
     "github/gh-aw-actions/setup@v0.63.0": {
       "repo": "github/gh-aw-actions/setup",
       "version": "v0.63.0",
@@ -14,6 +19,16 @@
       "repo": "github/gh-aw-actions/setup",
       "version": "v0.63.1",
       "sha": "53e09ec0be6271e81a69f51ef93f37212c8834b0"
+    },
+    "github/gh-aw-actions/setup@v0.64.5": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.64.5",
+      "sha": "5d2ebfd87a1a45a8a8323c1a12c01b055730dac5"
+    },
+    "github/gh-aw-actions/setup@v0.65.6": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.65.6",
+      "sha": "31130b20a8fd3ef263acbe2091267c0aace07e09"
     }
   }
 }

.github/skills/breaking-change-doc/Build-IssueComment.ps1

@@ -0,0 +1,94 @@
+# Build-IssueComment.ps1
+# Reads a breaking change issue draft markdown file, URL-encodes the title,
+# body, and labels, and produces a PR comment markdown file containing:
+#   - A header
+#   - The full draft for inline review
+#   - A clickable link that pre-fills a new issue in dotnet/docs
+#   - An email reminder
+#
+# Usage:
+#   pwsh .github/skills/breaking-change-doc/Build-IssueComment.ps1 `
+#       -IssueDraftPath issue-draft.md `
+#       -Title "[Breaking change]: Something changed" `
+#       -OutputPath pr-comment.md
+#
+# The issue draft file should contain only the issue body markdown (no title).
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$IssueDraftPath,
+
+    [Parameter(Mandatory = $true)]
+    [string]$Title,
+
+    [string]$OutputPath = "pr-comment.md",
+
+    [string]$Labels = "breaking-change,Pri1,doc-idea",
+
+    [string]$DocsRepo = "dotnet/docs"
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Test-Path $IssueDraftPath)) {
+    Write-Error "Issue draft file not found: $IssueDraftPath"
+    exit 1
+}
+
+$issueBody = Get-Content -Path $IssueDraftPath -Raw -Encoding UTF8
+
+# URL-encode using .NET Uri class (same technique the old script used)
+$encodedTitle = [Uri]::EscapeDataString($Title)
+$encodedBody = [Uri]::EscapeDataString($issueBody)
+$encodedLabels = [Uri]::EscapeDataString($Labels)
+$encodedEmailSubject = [Uri]::EscapeDataString("[Breaking Change] $Title")
+
+$issueUrl = "https://github.com/$DocsRepo/issues/new?title=$encodedTitle&body=$encodedBody&labels=$encodedLabels"
+$notificationEmailUrl = "mailto:dotnetbcn@microsoft.com?subject=$encodedEmailSubject"
+
+$comment = @"
+## Breaking Change Documentation
+
+$issueBody
+
+---
+
+> [!NOTE]
+> This documentation was generated with AI assistance from Copilot.
+
+:point_right: **[Click here to create the issue in dotnet/docs]($issueUrl)**
+
+After creating the issue, please email a link to it to
+[.NET Breaking Change Notifications]($notificationEmailUrl).
+"@
+
+# GitHub comment body limit is 65536 characters. If the comment exceeds this,
+# replace the inline draft with a short summary pointing at the file.
+$maxCommentLength = 65000
+if ($comment.Length -gt $maxCommentLength) {
+    Write-Warning "Comment body ($($comment.Length) chars) exceeds GitHub limit. Truncating inline draft."
+    $comment = @"
+## Breaking Change Documentation
+
+The full draft is too large to display inline. See ``issue-draft.md`` in the
+workflow artifacts for the complete content.
+
+---
+
+> [!NOTE]
+> This documentation was generated with AI assistance from Copilot.
+
+:point_right: **[Click here to create the issue in dotnet/docs]($issueUrl)**
+
+After creating the issue, please email a link to it to
+[.NET Breaking Change Notifications]($notificationEmailUrl).
+"@
+}
+
+$comment | Out-File -FilePath $OutputPath -Encoding UTF8 -NoNewline
+
+Write-Host "Wrote PR comment to $OutputPath ($($comment.Length) characters)"
+Write-Host "Issue URL length: $($issueUrl.Length) characters"
+if ($issueUrl.Length -gt 8192) {
+    Write-Warning "URL exceeds 8192 characters. Some browsers may truncate it. Consider shortening the issue body."
+}

.github/skills/breaking-change-doc/Get-VersionInfo.ps1

@@ -0,0 +1,196 @@
+# Get-VersionInfo.ps1
+# Determines the .NET version context for a merged PR using the GitHub CLI (gh).
+#
+# Usage:
+#   pwsh .github/skills/breaking-change-doc/Get-VersionInfo.ps1 -PrNumber 114929
+#
+# Output: JSON object with LastTagBeforeMerge, FirstTagWithChange, EstimatedVersion
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$PrNumber,
+
+    [string]$SourceRepo = "dotnet/runtime",
+
+    [string]$BaseRef = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+function ConvertFrom-DotNetTag {
+    param([string]$tagName)
+
+    if (-not $tagName -or $tagName -eq "Unknown") {
+        return $null
+    }
+
+    if ($tagName -match '^v(\d+)\.(\d+)\.(\d+)(?:-(.+))?$') {
+        $major = [int]$matches[1]
+        $minor = [int]$matches[2]
+        $build = [int]$matches[3]
+        $prerelease = if ($matches[4]) { $matches[4] } else { $null }
+
+        $prereleaseType = $null
+        $prereleaseNumber = $null
+
+        if ($prerelease -and $prerelease -match '^([a-zA-Z]+)\.(\d+)') {
+            $rawType = $matches[1]
+            $prereleaseNumber = [int]$matches[2]
+
+            if ($rawType -ieq "rc") {
+                $prereleaseType = "RC"
+            } else {
+                $prereleaseType = $rawType.Substring(0, 1).ToUpper() + $rawType.Substring(1).ToLower()
+            }
+        }
+
+        return @{
+            Major            = $major
+            Minor            = $minor
+            Build            = $build
+            Prerelease       = $prerelease
+            PrereleaseType   = $prereleaseType
+            PrereleaseNumber = $prereleaseNumber
+            IsRelease        = $null -eq $prerelease
+        }
+    }
+
+    return $null
+}
+
+function Format-DotNetVersion {
+    param($parsedTag)
+
+    if (-not $parsedTag) {
+        return "Next release"
+    }
+
+    $baseVersion = ".NET $($parsedTag.Major).$($parsedTag.Minor)"
+
+    if ($parsedTag.IsRelease) {
+        return $baseVersion
+    }
+
+    if ($parsedTag.PrereleaseType -and $parsedTag.PrereleaseNumber) {
+        return "$baseVersion $($parsedTag.PrereleaseType) $($parsedTag.PrereleaseNumber)"
+    }
+
+    return "$baseVersion ($($parsedTag.Prerelease))"
+}
+
+function Get-EstimatedNextVersion {
+    param($parsedTag, [string]$baseRef)
+
+    if (-not $parsedTag) {
+        return "Next release"
+    }
+
+    $isMainBranch = $baseRef -eq "main"
+
+    if ($parsedTag.IsRelease) {
+        if ($isMainBranch) {
+            $nextMajor = $parsedTag.Major + 1
+            return ".NET $nextMajor.0 Preview 1"
+        } else {
+            return ".NET $($parsedTag.Major).$($parsedTag.Minor)"
+        }
+    }
+
+    if ($isMainBranch -and $parsedTag.PrereleaseType -eq "RC") {
+        $nextMajor = $parsedTag.Major + 1
+        return ".NET $nextMajor.0 Preview 1"
+    } else {
+        $nextPreview = $parsedTag.PrereleaseNumber + 1
+        return ".NET $($parsedTag.Major).$($parsedTag.Minor) $($parsedTag.PrereleaseType) $nextPreview"
+    }
+}
+
+try {
+    # Step 1: Get PR merge info via GitHub CLI
+    $prJson = gh pr view $PrNumber --repo $SourceRepo --json mergeCommit,mergedAt,baseRefName 2>$null
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to fetch PR #$PrNumber from $SourceRepo"
+    }
+    $prData = $prJson | ConvertFrom-Json
+
+    $targetCommit = $prData.mergeCommit.oid
+    $mergedAt = $prData.mergedAt
+
+    if (-not $BaseRef) {
+        $BaseRef = $prData.baseRefName
+    }
+
+    # Step 2: Get recent releases (tags with published dates) in a single API call
+    $releasesJson = gh release list --repo $SourceRepo --limit 100 --json tagName,publishedAt 2>$null
+    $releases = @()
+    if ($LASTEXITCODE -eq 0 -and $releasesJson) {
+        $releases = @($releasesJson | ConvertFrom-Json)
+    }
+
+    # Filter to .NET version tags (v{major}.{minor}.{patch}[-prerelease]) with a valid publishedAt
+    $versionReleases = @($releases | Where-Object { $_.tagName -match '^v\d+\.\d+\.\d+' -and $_.publishedAt })
+
+    $lastTagBefore = "Unknown"
+    $firstTagWith = "Not yet released"
+
+    if ($mergedAt -and $versionReleases.Count -gt 0) {
+        $mergedAtDate = [DateTimeOffset]::Parse($mergedAt)
+
+        # Find the most recent release published before the merge
+        $beforeMerge = @($versionReleases |
+            Where-Object { [DateTimeOffset]::Parse($_.publishedAt) -lt $mergedAtDate } |
+            Sort-Object { [DateTimeOffset]::Parse($_.publishedAt) } -Descending)
+
+        if ($beforeMerge.Count -gt 0) {
+            $lastTagBefore = $beforeMerge[0].tagName
+        }
+
+        # Find candidate releases published at or after the merge, oldest first
+        $afterMerge = @($versionReleases |
+            Where-Object { [DateTimeOffset]::Parse($_.publishedAt) -ge $mergedAtDate } |
+            Sort-Object { [DateTimeOffset]::Parse($_.publishedAt) })
+
+        # Verify containment via the compare API: behind_by == 0 means the tag
+        # includes every commit reachable from the merge commit.
+        if ($targetCommit -and $afterMerge.Count -gt 0) {
+            foreach ($release in $afterMerge) {
+                $tag = $release.tagName
+                $behindBy = gh api "repos/$SourceRepo/compare/${targetCommit}...${tag}" --jq '.behind_by' 2>$null
+                if ($LASTEXITCODE -eq 0 -and $behindBy -match '^\d+$' -and [int]$behindBy -eq 0) {
+                    $firstTagWith = $tag
+                    break
+                }
+            }
+        }
+    }
+
+    # Step 3: Estimate version
+    $estimatedVersion = "Next release"
+
+    if ($firstTagWith -ne "Not yet released") {
+        $parsedFirstTag = ConvertFrom-DotNetTag $firstTagWith
+        $estimatedVersion = Format-DotNetVersion $parsedFirstTag
+    } else {
+        $parsedLastTag = ConvertFrom-DotNetTag $lastTagBefore
+        $estimatedVersion = Get-EstimatedNextVersion $parsedLastTag $BaseRef
+    }
+
+    # Output as JSON
+    @{
+        LastTagBeforeMerge = $lastTagBefore
+        FirstTagWithChange = $firstTagWith
+        EstimatedVersion   = $estimatedVersion
+        MergeCommit        = $targetCommit
+        MergedAt           = $mergedAt
+        BaseRef            = $BaseRef
+    } | ConvertTo-Json
+
+} catch {
+    # Return error info as JSON so the agent can handle it
+    @{
+        LastTagBeforeMerge = "Unknown"
+        FirstTagWithChange = "Not yet released"
+        EstimatedVersion   = "Next release"
+        Error              = $_.Exception.Message
+    } | ConvertTo-Json
+}