psake · tablackburn · Jul 22, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 22, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,17 @@ 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')`. 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.
+
 ### Fixed
 
 - [**#102**](https://github.com/psake/PowerShellBuild/issues/102)

diff --git 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
@@ -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+; 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.
 
 ## AI-assisted migration
 
@@ -77,34 +78,31 @@ 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.
-
-<!--
-TEMPLATE / EXAMPLE ENTRY — for PR contributors only; not rendered to
-readers. Copy this structure for a real entry. It uses a FICTIONAL change
-to demonstrate the format; the first real entry's PR can remove this
-comment block.
-
-### `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption` parameter
-
-The function `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption`
-parameter to `-StandardOption`. The behavior is otherwise unchanged.
-
-**Before (0.8.x):**
-
-    Invoke-PSBuildPlaceholder -LegacyOption 'value'
+### Minimum supported PowerShell version is now 5.1
 
-**After (1.0.0):**
+The module manifest now declares `PowerShellVersion = '5.1'` (previously
+`'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.
 
-    Invoke-PSBuildPlaceholder -StandardOption 'value'
+The previous `'3.0'` floor was aspirational — the module's dependencies
+(Pester 5+, BuildHelpers, psake) and its own code have required a newer
+engine for some time. The manifest now states the contract that is
+actually tested.
 
-You will see a parameter-binding error referencing `LegacyOption` if you
-do not migrate.
+No build-file code change is needed. If you run your build on an engine
+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+.
 
-Tracked in PR #999.
--->
+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)
 
@@ -130,9 +128,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
@@ -18,8 +18,10 @@
 - **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). 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
 
@@ -237,7 +239,7 @@
 Tests live in `tests/` and run on **Pester 6.0.0** (pinned exactly in `requirements.psd1`;
 see psake/PowerShellBuild#17 for the targeting decision). Write assertions with the classic
 `Should -Be` syntax — valid in both Pester 5 and 6 — rather than the Pester 6-only `Should-*`
 assertion family, so tests remain backportable. The shipped module's own Pester compatibility
 floor (5.0.0 in `Test-PSBuildPester`) is a separate contract and is unchanged.

 - Always build the module before running Pester directly — running against source can produce
@@ -266,7 +268,7 @@

 - Triggers: manual dispatch, GitHub release published
 - Runs on: `ubuntu-latest`
 - Reads `PSGALLERY_API_KEY` secret, converts to `PSCredential`, runs
  `./build.ps1 -Task Publish -PSGalleryApiKey $cred -Bootstrap`

 ## Repo-Specific Conventions
@@ -347,9 +349,9 @@
 | ------------------------- | ---------------------------------------------------- |
 | `$env:BHProjectPath`      | Repository root directory                            |
 | `$env:BHProjectName`      | Module name (from directory structure)               |
 | `$env:BHPSModulePath`     | Path to module source directory                      |
 | `$env:BHPSModuleManifest` | Path to `.psd1` manifest                             |
 | `$env:BHModulePath`       | Same as `BHPSModulePath`                             |
 | `$env:BHBuildSystem`      | Detected CI system (e.g., `GitHubActions`, `Unknown`)|
 | `$env:BHBranchName`       | Current git branch                                   |
 | `$env:BHCommitMessage`    | Latest git commit message                            |