diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c20229..5da6b45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ### 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) diff --git a/PowerShellBuild/PowerShellBuild.psd1 b/PowerShellBuild/PowerShellBuild.psd1 index e87cd1b..a0b539b 100644 --- a/PowerShellBuild/PowerShellBuild.psd1 +++ b/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' diff --git a/README.md b/README.md index 05c2e42..0249cb9 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,10 @@ consistency ultimately helps the community in building high-quality PowerShell 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 diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index d9612b3..192d430 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -41,6 +41,8 @@ One line per break; follow the link for details and migration steps. - [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 @@ processes. 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