feat!: Raise the consumer psake floor to 5.0.4

CHANGELOG.md

@@ -9,6 +9,16 @@
 
 ### Changed
 
+- [**#166**](https://github.com/psake/PowerShellBuild/issues/166)
+  **Breaking:** the consumer psake floor in `RequiredModules` is raised from
+  `4.9.0` to `5.0.4`. psake 4.x is no longer supported. `RequiredModules` is
+  enforced at import, so a consumer with only psake 4.x installed cannot import
+  the module at all. The lower floor was untested — CI has exercised only 5.0.4
+  since the toolchain moved there in #162 — so it asserted support nothing
+  verified. Invoke-Build users are unaffected. See the
+  [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md); most v4 build
+  scripts work under v5 unchanged.
+
 - [**#105**](https://github.com/psake/PowerShellBuild/issues/105)
   **Breaking:** help generation moved from `platyPS` 0.14.x to
   [`Microsoft.PowerShell.PlatyPS`](https://www.powershellgallery.com/packages/Microsoft.PowerShell.PlatyPS)
@@ -88,7 +98,7 @@
   that passed before may now correctly fail.
 - [**#96**](https://github.com/psake/PowerShellBuild/issues/96)
   `Test-PSBuildScriptAnalysis` no longer fails with a path-resolution error
   when `SettingsPath` is not supplied. An unsupplied path was forwarded to
   PSScriptAnalyzer as `-Settings ''`, which resolved against the current
   directory and threw before any analysis ran, so the function's own
   documented example could not run as written.

PowerShellBuild/PowerShellBuild.psd1

@@ -11,7 +11,7 @@
     RequiredModules      = @(
         @{ModuleName = 'BuildHelpers'; ModuleVersion = '2.0.16' }
         @{ModuleName = 'Pester'; ModuleVersion = '5.6.1' }
-        @{ModuleName = 'psake'; ModuleVersion = '4.9.0' }
+        @{ModuleName = 'psake'; ModuleVersion = '5.0.4' }
     )
     FunctionsToExport    = @(
         'Build-PSBuildMAMLHelp'

README.md

@@ -14,11 +14,10 @@
 modules.
 
 > If using [psake](https://github.com/psake/psake) as your task runner, version
-> `4.8.0` or greater is required to make use of shared tasks distributed in
-> separate modules. To install psake `4.8.0` you can run:
+> `5.0.4` or greater is required. To install psake you can run:
 
 ```powershell
-Install-Module -Name psake -RequiredVersion 4.8.0 -Repository PSGallery
+Install-Module -Name psake -MinimumVersion 5.0.4 -Repository PSGallery
 ```
 
 > For [Invoke-Build](https://github.com/nightroman/Invoke-Build), see the
@@ -26,7 +25,7 @@
 > example.
 
 <p align="center">
     <img src="media/psaketaskmodule-256x256.png" alt="Logo">
 </p>
 
 ## Status - Work in progress
@@ -87,10 +86,10 @@
 | Setting                                                     | Default value                               | Description                                                                                                                                                                  |
 |-------------------------------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | $PSBPreference.General.ProjectRoot                          | `$env:BHProjectPath`                        | Root directory for the project                                                                                                                                               |
 | $PSBPreference.General.SrcRootDir                           | `$env:BHPSModulePath`                       | Root directory for the module                                                                                                                                                |
 | $PSBPreference.General.ModuleName                           | `$env:BHProjectName`                        | The name of the module. This should match the basename of the PSD1 file                                                                                                      |
 | $PSBPreference.General.ModuleVersion                        | `\<computed>`                               | The version of the module                                                                                                                                                    |
 | $PSBPreference.General.ModuleManifestPath                   | `$env:BHPSModuleManifest`                   | Path to the module manifest (PSD1)                                                                                                                                           |
 | $PSBPreference.Build.OutDir                                 | `$projectRoot/Output`                       | Output directory when building the module                                                                                                                                    |
 | $PSBPreference.Build.Dependencies                           | 'StageFiles, 'BuildHelp'                    | Default task dependencies for the `Build` task                                                                                                                               |
 | $PSBPreference.Build.ModuleOutDir                           | `$outDir/$moduleName/$moduleVersion`        | `For internal use only. Do not overwrite. Use '$PSBPreference.Build.OutDir' to set output directory`                                                                         |
@@ -123,10 +122,10 @@
 | $PSBPreference.Docs.RootDir                                 | `$projectRoot/docs`                         | Directory PlatyPS markdown documentation will be saved to                                                                                                                    |
 | $PSBPreference.Docs.Overwrite                               | `$false`                                    | Overwrite the markdown files in the docs folder using the comment based help as the source of truth.                                                                         |
 | $PSBPreference.Docs.AlphabeticParamsOrder                   | `$false`                                    | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. |
 | $PSBPreference.Docs.ExcludeDontShow                         | `$false`                                    | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.                                                                              |
 | $PSBPreference.Docs.UseFullTypeName                         | `$false`                                    | Indicates that the target document will use a full type name instead of a short name for parameters.                                                                         |
 | $PSBPreference.Publish.PSRepository                         | `PSGallery`                                 | PowerShell repository name to publish                                                                                                                                        |
 | $PSBPreference.Publish.PSRepositoryApiKey                   | `$env:PSGALLERY_API_KEY`                    | API key to authenticate to PowerShell repository with                                                                                                                        |
 | $PSBPreference.Publish.PSRepositoryCredential               | `$null`                                     | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined                                                                         |
 
 ## Modifying Task Dependencies

docs/migration-v0.8-to-v1.0.md

@@ -41,6 +41,8 @@
 - [A committed `docs/` tree converts itself on the first build](#a-committed-docs-tree-converts-itself-on-the-first-build)
   — the schema conversion is automatic; review the diff for the prose it
   drops, and convert orphaned documents by hand.
+- [psake 4.x is no longer supported; the floor is now 5.0.4](#psake-4x-is-no-longer-supported-the-floor-is-now-504)
+  — psake users must upgrade to 5.0.4+; Invoke-Build users are unaffected.
 
 > More entries will follow as the remaining Phase 2 work lands.
 
@@ -591,6 +593,69 @@
 
 Related: [#154](https://github.com/psake/PowerShellBuild/issues/154).
 
+### psake 4.x is no longer supported; the floor is now 5.0.4
+
+`RequiredModules` requires **psake 5.0.4 or newer**, previously 4.9.0. If you
+use Invoke-Build rather than psake, nothing here applies to you.
+
+`RequiredModules` is enforced when the module is imported, so this is not a
+degraded experience — with only psake 4.x installed,
+`Import-Module PowerShellBuild` fails outright.
+
+**Migration:**
+
+```powershell
+Install-Module -Name psake -MinimumVersion 5.0.4 -Repository PSGallery
+```
+
+If you pin psake in a `requirements.psd1` or equivalent, raise the pin there
+too — installing PowerShellBuild will pull a satisfying psake, but a pinned
+4.9.x will still be the one your build imports.
+
+**Detection:** `Import-Module PowerShellBuild` fails with a message that the
+required module `psake` is not installed, naming version `5.0.4`.
+
+**What upgrading psake costs you.** Per
+[psake's own v4-to-v5 migration guide](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md),
+most v4 build scripts work unchanged. The `Task ... -Depends` syntax,
+`-FromModule`, and `$psake.build_success` are all explicitly retained — this
+repository still uses all three. The breaks are:
+
+- `default.ps1` is no longer auto-detected — rename it to `psakefile.ps1`, or
+  pass `-BuildFile`. PowerShellBuild's own convention has always been
+  `psakeFile.ps1`, so this is unlikely to affect you.
+- The standalone `psake.ps1` and `psake.cmd` runners are gone — use
+  `Import-Module psake; Invoke-psake`. Again unlikely, since the documented
+  PowerShellBuild pattern is a `build.ps1` wrapper.
+- `Invoke-psake` now returns a `PsakeBuildResult` where v4 returned nothing.
+  This only matters if your wrapper assigns or pipes the result;
+  `$psake.build_success` still works.
+- The `OutputHandler`, `OutputHandlers`, and `ColoredOutput` configuration
+  options are removed. Use `$env:NO_COLOR`, `-OutputFormat`, or `-Quiet`.
+- .NET Framework older than 4.0 is unsupported and the default `Framework`
+  moved from `4.0` to `4.7.2`, and the `$framework` global is gone. Neither
+  affects PowerShell module builds.
+- psake 5 requires PowerShell 5.1 (v4 declared 3.0) — already the
+  PowerShellBuild floor, so no additional constraint.
+
+**Why the floor moved.** The floors this module declares were not all earned
+the same way. Pester's floor is lower than the version we build with, and that
+is deliberate: `Test-PSBuildPester` supports both Pester majors and CI proves
+it on every run. The psake floor was lower *and untested* — CI has exercised
+only 5.0.4 since the toolchain moved there, so 4.9.0 was a claim rather than a
+guarantee. Rather than keep asserting support nothing verifies, the floor now
+matches what is tested.
+
+**One thing you gain.** psake 5 stops silently swallowing an escaping `break`.
+Under 4.9.x, a `break` leaking out of a Pester `BeforeAll` — which
+BuildHelpers' `Get-BuildVariable` does — is absorbed, so the test container
+fails invisibly and the build still passes. In this repository that was twelve
+tests that had not been running. If your Pester tests call
+`Set-BuildEnvironment`, upgrading may surface failures that were always there.
+
+Decision and evidence in
+[#166](https://github.com/psake/PowerShellBuild/issues/166).
+
 ## Adding an entry (for PR contributors)
 
 Every breaking-change PR that lands in v1.0.0 must add an entry here for