ci(release): build release notes from CHANGELOG; auto-populate PSData.ReleaseNotes; harden version expansion

.github/workflows/PublishModuleToPowerShellGallery.yaml

@@ -54,21 +54,24 @@ jobs:
  shell: bash
  env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ VERSION: ${{ steps.version.outputs.version }}
  run: |
- if gh release view "v${{ steps.version.outputs.version }}" > /dev/null 2>&1; then
+ if gh release view "v$VERSION" > /dev/null 2>&1; then
  echo "exists=true" >> $GITHUB_OUTPUT
- echo "GitHub release v${{ steps.version.outputs.version }} already exists"
+ echo "GitHub release v$VERSION already exists"
  else
  echo "exists=false" >> $GITHUB_OUTPUT
- echo "GitHub release v${{ steps.version.outputs.version }} does not exist"
+ echo "GitHub release v$VERSION does not exist"
  fi
 
  - name: Check if PSGallery Version Exists
  id: check_psgallery
  if: steps.check_release.outputs.exists == 'false'
  shell: pwsh
+ env:
+ VERSION: ${{ steps.version.outputs.version }}
  run: |
- $version = "${{ steps.version.outputs.version }}"
+ $version = $env:VERSION
  $published = Find-Module -Name {{ModuleName}} -RequiredVersion $version -Repository PSGallery -ErrorAction SilentlyContinue
  if ($published) {
  Write-Host "PSGallery version $version already exists"
@@ -85,13 +88,60 @@ jobs:
 
  - name: Create GitHub Release
  if: steps.check_release.outputs.exists == 'false'
- shell: bash
+ shell: pwsh
  env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ REPOSITORY: ${{ github.repository }}
+ VERSION: ${{ steps.version.outputs.version }}
  run: |
- gh release create "v${{ steps.version.outputs.version }}" \
- --title "v${{ steps.version.outputs.version }}" \
- --generate-notes
+ $version = $env:VERSION
+
+ # Build release notes from this version's CHANGELOG.md section so the release
+ # body carries only the curated, user-facing entries (not the full PR list that
+ # --generate-notes produces, which is dominated by bot/CI/chore PRs).
+ # Read defensively: a missing/unreadable CHANGELOG.md must fall back to
+ # --generate-notes (below), never fail the publish.
+ $changelogLines = $null
+ if (Test-Path -LiteralPath './CHANGELOG.md') {
+ try {
+ $changelogLines = Get-Content -LiteralPath './CHANGELOG.md' -ErrorAction Stop
+ }
+ catch {
+ Write-Host "::warning::Could not read CHANGELOG.md ($($_.Exception.Message)); falling back to auto-generated notes."
+ }
+ }
+ $captured = [System.Collections.Generic.List[string]]::new()
+ if ($changelogLines) {
+ $headerPattern = '^##\s+\[' + [regex]::Escape($version) + '\]'
+ $capturing = $false
+ foreach ($line in $changelogLines) {
+ if (-not $capturing) {
+ if ($line -match $headerPattern) { $capturing = $true }
+ continue
+ }
+ if ($line -match '^##\s+\[') { break } # next version header ends the section
+ $captured.Add($line)
+ }
+ }
+ $body = ($captured -join "`n").Trim()
+
+ if ([string]::IsNullOrWhiteSpace($body)) {
+ Write-Host "::warning::No CHANGELOG.md section found for $version; falling back to auto-generated notes."
+ gh release create "v$version" --title "v$version" --generate-notes
+ }
+ else {
+ # Append a compare link against the most recent existing tag. The v$version
+ # tag does not exist yet (this step creates it), so the latest tag is the
+ # previous release.
+ $previousTag = git tag --list 'v*' --sort=-version:refname |
+ Where-Object { $_ -ne "v$version" } |
+ Select-Object -First 1
+ if ($previousTag) {
+ $body += "`n`n**Full Changelog**: https://github.com/$env:REPOSITORY/compare/$previousTag...v$version"
+ }
+ Set-Content -LiteralPath './release-notes.md' -Value $body -Encoding utf8
+ gh release create "v$version" --title "v$version" --notes-file './release-notes.md'
+ }
 
  - name: Publish to PSGallery
  if: steps.check_release.outputs.exists == 'false' && steps.check_psgallery.outputs.exists == 'false'

build.depend.psd1

@@ -25,4 +25,9 @@
  'PSScriptAnalyzer' = @{
  Version = '1.25.0'
  }
+ # Parses CHANGELOG.md (Keep a Changelog format) so the Publish task can populate the
+ # built manifest's PSData.ReleaseNotes from the matching version's entry.
+ 'ChangelogManagement' = @{
+ Version = '3.1.0'
+ }
 }

build.psake.ps1

@@ -45,5 +45,50 @@ Task -Name 'Init_Integration' -Description 'Load integration test environment va
  }
 }
 
+# Populate the built manifest's ReleaseNotes from the matching CHANGELOG.md entry so the
+# PowerShell Gallery release-notes panel shows the curated, user-facing notes (the same
+# content used for the GitHub release) instead of just a link. Depends on Build so the
+# staged manifest in ModuleOutDir exists; runs before Publish (see $PSBPublishDependency
+# below). Non-fatal if the changelog can't be read or has no entry for the version being
+# published, so a release is never blocked.
+Task -Name 'UpdateReleaseNotes' -Depends 'Build' -Description 'Set built manifest ReleaseNotes from the matching CHANGELOG.md entry' {
+ $changelogPath = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.md'
+ if (-not (Test-Path -Path $changelogPath)) {
+ Write-Warning 'CHANGELOG.md not found; leaving ReleaseNotes unchanged.'
+ return
+ }
+
+ $moduleVersion = $PSBPreference.General.ModuleVersion
+ try {
+ Import-Module -Name 'ChangelogManagement' -ErrorAction Stop
+ $changelogData = Get-ChangelogData -Path $changelogPath -ErrorAction Stop
+ }
+ catch {
+ Write-Warning "Could not read CHANGELOG.md ($($_.Exception.Message)); leaving ReleaseNotes unchanged."
+ return
+ }
+
+ $releaseEntry = $changelogData.Released |
+ Where-Object { [string]$_.Version -eq [string]$moduleVersion } |
+ Select-Object -First 1
+ if (-not $releaseEntry) {
+ Write-Warning "No CHANGELOG.md entry found for version $moduleVersion; leaving ReleaseNotes unchanged."
+ return
+ }
+
+ $releaseNotes = $releaseEntry.RawData.Trim()
+ if ([string]::IsNullOrWhiteSpace($releaseNotes)) {
+ Write-Warning "CHANGELOG.md entry for version $moduleVersion is empty; leaving ReleaseNotes unchanged."
+ return
+ }
+ $builtManifest = Join-Path -Path $PSBPreference.Build.ModuleOutDir -ChildPath "$($PSBPreference.General.ModuleName).psd1"
+ Update-ModuleManifest -Path $builtManifest -ReleaseNotes $releaseNotes -ErrorAction Stop
+ Write-Host " Set ReleaseNotes on built manifest from CHANGELOG [$($releaseEntry.Version)] ($($releaseNotes.Length) chars)" -ForegroundColor Gray
+}
+
+# Inject ReleaseNotes into the built manifest before publishing (PowerShellBuild's Publish
+# defaults to depending only on 'Test').
+$PSBPublishDependency = @('Test', 'UpdateReleaseNotes')
+
 # Note: -Depends replaces PowerShellBuild's default dependencies, so we must include Pester and Analyze explicitly
 Task -Name 'Test' -FromModule 'PowerShellBuild' -MinimumVersion '0.7.3' -Depends 'Init_Integration', 'Pester', 'Analyze'