From ee8535597c4bdcf77e6504e1b39fd73024b8c2c0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 23:21:03 +0000 Subject: [PATCH 1/3] chore: Raise minimum PowerShell version to 5.1 in module manifest - PowerShellVersion '3.0' -> '5.1'; add CompatiblePSEditions Desktop/Core - Add the first migration-guide entry documenting the new platform floor - Record the change in the changelog under Unreleased - Refresh the stale manifest note in repository-specific instructions BREAKING CHANGE: the manifest now blocks import on PowerShell older than 5.1. Supported and CI-tested platforms are Windows PowerShell 5.1 and PowerShell 7.4+. Decision record: psake/PowerShellBuild#120. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BxrhSpD47TSrS9hEJpDMaH --- CHANGELOG.md | 10 +++ PowerShellBuild/PowerShellBuild.psd1 | 29 ++++---- docs/migration-v0.8-to-v1.0.md | 71 +++++++++---------- .../repository-specific.instructions.md | 5 +- 4 files changed, 60 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc53d26..023216e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased +### Changed + +- [**#120**](https://github.com/psake/PowerShellBuild/issues/120) + **Breaking:** the module manifest now requires PowerShell 5.1 or newer + (`PowerShellVersion = '5.1'`, previously `'3.0'`) and declares + `CompatiblePSEditions = @('Desktop', 'Core')`. Supported and CI-tested + platforms are Windows PowerShell 5.1 and PowerShell 7.4+. See the + [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) for + details. + ### Fixed - [**#102**](https://github.com/psake/PowerShellBuild/issues/102) diff --git a/PowerShellBuild/PowerShellBuild.psd1 b/PowerShellBuild/PowerShellBuild.psd1 index 2f4f0a5..16538fc 100644 --- a/PowerShellBuild/PowerShellBuild.psd1 +++ b/PowerShellBuild/PowerShellBuild.psd1 @@ -1,19 +1,20 @@ @{ - RootModule = 'PowerShellBuild.psm1' - ModuleVersion = '0.8.2' - GUID = '15431eb8-be2d-4154-b8ad-4cb68a488e3d' - Author = 'Brandon Olin' - CompanyName = 'Community' - Copyright = '(c) Brandon Olin. All rights reserved.' - Description = 'A common psake and Invoke-Build task module for PowerShell projects' - PowerShellVersion = '3.0' - RequiredModules = @( + RootModule = 'PowerShellBuild.psm1' + ModuleVersion = '0.8.2' + GUID = '15431eb8-be2d-4154-b8ad-4cb68a488e3d' + Author = 'Brandon Olin' + CompanyName = 'Community' + Copyright = '(c) Brandon Olin. All rights reserved.' + Description = 'A common psake and Invoke-Build task module for PowerShell projects' + PowerShellVersion = '5.1' + CompatiblePSEditions = @('Desktop', 'Core') + RequiredModules = @( @{ModuleName = 'BuildHelpers'; ModuleVersion = '2.0.16' } @{ModuleName = 'Pester'; ModuleVersion = '5.6.1' } @{ModuleName = 'platyPS'; ModuleVersion = '0.14.1' } @{ModuleName = 'psake'; ModuleVersion = '4.9.0' } ) - FunctionsToExport = @( + FunctionsToExport = @( 'Build-PSBuildMAMLHelp' 'Build-PSBuildMarkdown' 'Build-PSBuildModule' @@ -27,10 +28,10 @@ 'Test-PSBuildPester' 'Test-PSBuildScriptAnalysis' ) - CmdletsToExport = @() - VariablesToExport = @() - AliasesToExport = @('*tasks') - PrivateData = @{ + CmdletsToExport = @() + VariablesToExport = @() + AliasesToExport = @('*tasks') + PrivateData = @{ PSData = @{ Tags = @('psake', 'build', 'InvokeBuild') LicenseUri = 'https://raw.githubusercontent.com/psake/PowerShellBuild/master/LICENSE' diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index 4bc90a7..f4324d5 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -1,11 +1,11 @@ # Migrating from PowerShellBuild v0.8 to v1.0 -> 🚧 **Pre-release.** v1.0.0 has not shipped yet, and no breaking changes -> have been documented here. This guide is being prepared alongside the -> v1.0.0 work; entries are added by each breaking-change PR as it lands. -> Track progress in +> 🚧 **Pre-release.** v1.0.0 has not shipped yet. This guide is being +> prepared alongside the v1.0.0 work; entries are added by each +> breaking-change PR as it lands. Track progress in > [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120). -> If you are on 0.8.x today, there is nothing to migrate yet. +> If you are on 0.8.x today, no action is needed until you upgrade to a +> 1.0.0 prerelease or release. This guide helps you upgrade a consumer `build.ps1` (or equivalent) from PowerShellBuild **0.8.x** to **1.0.0**. @@ -15,13 +15,14 @@ do not require user action, see [`CHANGELOG.md`](../CHANGELOG.md). ## Quick Start -> **Status:** no breaking changes have landed yet. This list will be -> populated by Phase 2 PRs as the migration to Microsoft.PowerShell.PlatyPS -> 1.x and psake 5.x progresses. -> -> Once entries exist, this section will summarize each break in one line -> with a link into the body below — so you can scan what's likely to -> affect you before reading the details. +One line per break; follow the link for details and migration steps. + +- [Minimum supported PowerShell version is now 5.1](#minimum-supported-powershell-version-is-now-51) + — the manifest requires PowerShell 5.1+; supported and CI-tested + platforms are Windows PowerShell 5.1 and PowerShell 7.4+. + +> More entries will follow as the Phase 2 migrations to +> Microsoft.PowerShell.PlatyPS 1.x and psake 5.x land. ## AI-assisted migration @@ -77,34 +78,27 @@ PowerShellBuild conventions worth knowing: ## Migration entries -_No breaking changes documented yet._ Each breaking-change PR adds its -entry here as it lands; see [Adding an entry](#adding-an-entry-for-pr-contributors) -below for the format. - - +Decision record and platform validation details: +[#120 (comment)](https://github.com/psake/PowerShellBuild/issues/120#issuecomment-5028978464). ## Adding an entry (for PR contributors) @@ -130,9 +124,8 @@ Also: to your new entry's heading. - Reference this guide from your PR description (the entry it adds). -A commented-out template entry lives in the **Migration entries** section -above (visible only in the raw Markdown) — copy it as a starting point. -The first real entry's PR can remove that comment block. +Use the existing entries in the **Migration entries** section above as a +model for structure and tone. ## Related diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 6861aa3..c231b13 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -18,8 +18,9 @@ tasks for other PowerShell module projects. It supports two task-runner framewor - **Invoke-Build** - Current version: see `ModuleVersion` in `PowerShellBuild/PowerShellBuild.psd1` -- `PowerShellVersion` in the manifest is currently `'3.0'` — almost certainly wrong; under - review in the v1.0.0 roadmap (psake/PowerShellBuild#120) +- `PowerShellVersion` in the manifest is `'5.1'` with `CompatiblePSEditions = @('Desktop', 'Core')` + — decided in the v1.0.0 roadmap (psake/PowerShellBuild#120). Supported and CI-tested platforms + are Windows PowerShell 5.1 and PowerShell 7.4+ - Cross-platform: Windows, Linux, macOS (CI matrix in `.github/workflows/test.yml`) - The module is **psake/PowerShellBuild** on PSGallery and GitHub; maintained by the psake org From 37b7c4763fd053e4be64dc06003950dd39a50031 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 23:21:54 +0000 Subject: [PATCH 2/3] docs: Add PR reference to the minimum-version migration entry Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BxrhSpD47TSrS9hEJpDMaH --- docs/migration-v0.8-to-v1.0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index f4324d5..07936ef 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -97,7 +97,9 @@ older than 5.1, `Import-Module PowerShellBuild` fails with an error that the module "requires a minimum PowerShell version of '5.1'" — migrate by running the build under Windows PowerShell 5.1 or PowerShell 7.4+. -Decision record and platform validation details: +Tracked in PR +[#141](https://github.com/psake/PowerShellBuild/pull/141); decision +record and platform validation details in [#120 (comment)](https://github.com/psake/PowerShellBuild/issues/120#issuecomment-5028978464). ## Adding an entry (for PR contributors) From 79c5de0206100e1331c4cbb4a972a9fb6c05fe49 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 00:32:01 +0000 Subject: [PATCH 3/3] docs: Describe PowerShell 7.4+ as the support floor, not a CI-pinned version CI runs Windows PowerShell 5.1 and the runners' current PowerShell 7 release; it does not pin a 7.4 job. Reword the migration guide, changelog, and AIM instructions so 7.4+ reads as the support floor rather than a specifically CI-tested version, per PR review feedback. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BxrhSpD47TSrS9hEJpDMaH --- CHANGELOG.md | 5 +++-- docs/migration-v0.8-to-v1.0.md | 16 +++++++++------- instructions/repository-specific.instructions.md | 5 +++-- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 023216e..775791a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - [**#120**](https://github.com/psake/PowerShellBuild/issues/120) **Breaking:** the module manifest now requires PowerShell 5.1 or newer (`PowerShellVersion = '5.1'`, previously `'3.0'`) and declares - `CompatiblePSEditions = @('Desktop', 'Core')`. Supported and CI-tested - platforms are Windows PowerShell 5.1 and PowerShell 7.4+. See the + `CompatiblePSEditions = @('Desktop', 'Core')`. The support floor is + Windows PowerShell 5.1 or PowerShell 7.4+ (CI runs Windows PowerShell + 5.1 and the runners' current PowerShell 7 release). See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) for details. diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index 07936ef..0ecfa48 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -18,8 +18,8 @@ do not require user action, see [`CHANGELOG.md`](../CHANGELOG.md). One line per break; follow the link for details and migration steps. - [Minimum supported PowerShell version is now 5.1](#minimum-supported-powershell-version-is-now-51) - — the manifest requires PowerShell 5.1+; supported and CI-tested - platforms are Windows PowerShell 5.1 and PowerShell 7.4+. + — the manifest requires PowerShell 5.1+; the support floor is + Windows PowerShell 5.1 or PowerShell 7.4+. > More entries will follow as the Phase 2 migrations to > Microsoft.PowerShell.PlatyPS 1.x and psake 5.x land. @@ -81,11 +81,13 @@ PowerShellBuild conventions worth knowing: ### Minimum supported PowerShell version is now 5.1 The module manifest now declares `PowerShellVersion = '5.1'` (previously -`'3.0'`) and `CompatiblePSEditions = @('Desktop', 'Core')`. The supported -and CI-tested platforms for 1.0.0 are **Windows PowerShell 5.1** and -**PowerShell 7.4+**. PowerShell 3.0–5.0 can no longer import the module; -PowerShell 6.0–7.3 is not blocked by the manifest but is untested and -unsupported (the test toolchain, Pester 6, supports only 5.1 and 7.4+). +`'3.0'`) and `CompatiblePSEditions = @('Desktop', 'Core')`. The support +floor for 1.0.0 is **Windows PowerShell 5.1** or **PowerShell 7.4+**. +PowerShell 3.0–5.0 can no longer import the module; PowerShell 6.0–7.3 is +not blocked by the manifest but is untested and unsupported (the test +toolchain, Pester 6, supports only 5.1 and 7.4+). CI exercises Windows +PowerShell 5.1 and the runners' current PowerShell 7 release on Linux, +Windows, and macOS. The previous `'3.0'` floor was aspirational — the module's dependencies (Pester 5+, BuildHelpers, psake) and its own code have required a newer diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index c231b13..c10d30f 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -19,8 +19,9 @@ tasks for other PowerShell module projects. It supports two task-runner framewor - Current version: see `ModuleVersion` in `PowerShellBuild/PowerShellBuild.psd1` - `PowerShellVersion` in the manifest is `'5.1'` with `CompatiblePSEditions = @('Desktop', 'Core')` - — decided in the v1.0.0 roadmap (psake/PowerShellBuild#120). Supported and CI-tested platforms - are Windows PowerShell 5.1 and PowerShell 7.4+ + — decided in the v1.0.0 roadmap (psake/PowerShellBuild#120). The support floor is Windows + PowerShell 5.1 or PowerShell 7.4+; CI runs Windows PowerShell 5.1 and the runners' current + PowerShell 7 release across Linux/Windows/macOS - Cross-platform: Windows, Linux, macOS (CI matrix in `.github/workflows/test.yml`) - The module is **psake/PowerShellBuild** on PSGallery and GitHub; maintained by the psake org