From 00a88dd2016f8a746fa9aa30ef9e8c65ff1c7fbe Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Wed, 26 Aug 2026 18:26:53 -0400 Subject: [PATCH 1/2] feat!: Raise the consumer psake floor to 5.0.4 Closes #166. Part of #120 (Phase 3). BREAKING CHANGE: 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 floors this module declares were not all earned the same way. Pester's floor sits below the version the build uses, and that is deliberate -- Test-PSBuildPester supports both majors and the #137 matrix proves it on every run. The psake floor was lower AND untested: CI has exercised only 5.0.4 since #162 moved the toolchain, so 4.9.0 asserted support that nothing verified. #120 already flagged that under "Not yet specified". That left two honest options: add a psake 4.x CI leg, or stop claiming 4.x. For a volunteer project, maintaining a second task-runner matrix leg for a major nobody has asked for is the more expensive one, and 1.0.0 is the cheapest moment to move a floor. Deliberately not relied on, because neither survives checking: - "One supported major simplifies psakeFile.ps1" -- there is no version-conditional psake code anywhere today. IB.tasks.ps1 does not contain the string "psake", and psakeFile.ps1 touches only $psake.context.currentTaskName and $psake.context.Peek().Tasks.Keys, both present in 4.9.x and 5.0.4 alike. - "Nobody runs anything older than PowerShell 5.x" -- true, and already enforced by PowerShellVersion = '5.1' from #141. psake 4.9.1 runs fine on PowerShell 7, so a consumer can be fully current and still on psake 4. README.md was separately wrong and is fixed here: it claimed psake 4.8.0 was required while the manifest floor had been 4.9.0. Suite: 472 passed, 0 failed. Test-ModuleManifest validates against the raised floor. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_012AKaM9i6NyMFDcJNeC34h5 --- CHANGELOG.md | 736 ++++++++++++++------------- PowerShellBuild/PowerShellBuild.psd1 | 2 +- README.md | 5 +- docs/migration-v0.8-to-v1.0.md | 65 +++ 4 files changed, 441 insertions(+), 367 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c20229..df06aaa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,363 +1,373 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](http://keepachangelog.com/) -and this project adheres to [Semantic Versioning](http://semver.org/). - -## Unreleased - -### Changed - -- [**#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) - 1.x. PlatyPS is also no longer a `RequiredModules` entry, so - `Install-Module PowerShellBuild` no longer installs it — the two PlatyPS - modules cannot be loaded into one process, so forcing the new one into every - session would break any consumer still holding the old one. Install it - yourself if you build help. `$PSBPreference.Docs.AlphabeticParamsOrder` is - removed, because PlatyPS 1.x always sorts parameters alphabetically and - offers no way back. Generated markdown carries the 1.x schema, though its - on-disk layout is unchanged, and now includes a module landing page that - 0.14.x never produced. Updatable help is covered separately under **Fixed**. - See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). - -- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) - **Breaking:** `Test-PSBuildScriptAnalysis` now counts PSScriptAnalyzer - `ParseError` records alongside `Error`. A file that does not parse at all - previously satisfied no threshold — not even the strictest validated value, - `Information` — so it was reported and the build passed anyway. It now fails - every threshold except `None`. See the - [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build that - passed before may now correctly fail. - -- [**#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. - -### Added - -- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) - `Test-PSBuildScriptAnalysis` accepts `Any` as a `SeverityThreshold`, failing - the build on any diagnostic record regardless of severity. `Any` was already - documented in `build.properties.ps1` but was missing from the parameter's - `ValidateSet`, so setting - `$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Any'` failed - parameter binding instead of working as documented. - -### Fixed - -- [**#169**](https://github.com/psake/PowerShellBuild/issues/169) - `Build-PSBuildUpdatableHelp` produces a help cabinet. It never could before: - it needed a module landing page that `Build-PSBuildMarkdown` did not - generate, passed an undefined variable as the cabinet source folder, and was - never given the module name — so any build that reached the - `GenerateUpdatableHelp` task failed with a parameter-binding error. - `Build-PSBuildMarkdown` now writes the landing page, and the task passes the - module name and output path it always should have. Using the task requires a - `HelpInfoUri` in your module manifest; without one it warns and produces - nothing, rather than writing a cabinet with no `HelpInfo.xml` to find it by. - See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). - -- [**#147**](https://github.com/psake/PowerShellBuild/issues/147) - `Test-PSBuildScriptAnalysis` retries the analysis when a PSScriptAnalyzer rule - crashes on an internal race - ([PSScriptAnalyzer#1538](https://github.com/PowerShell/PSScriptAnalyzer/issues/1538)), - which is unrelated to the code being analyzed and succeeds on a re-run. - Consumers who set `$ErrorActionPreference = 'Stop'` — common in a build script — - previously got a randomly red build. A crash that survives every attempt is - still surfaced, so a persistent failure behaves as it did before. - -- [**#96**](https://github.com/psake/PowerShellBuild/issues/96) - `Test-PSBuildScriptAnalysis` now fails the build when PSScriptAnalyzer - reports findings at or above the configured severity threshold. The - severity counts were computed from `$_Severity` — an undefined variable — - instead of `$_.Severity`, so all three counts were always zero and the - `Error`, `Warning`, and `Information` thresholds could never fail a build. - Script analysis reported its findings and the build passed regardless. - Because the default `FailBuildOnSeverityLevel` is `Error`, any consumer - running the `Analyze` task had a gate that only ever looked like it was - working. See the - [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build - 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. -- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) - `Test-PSBuildPester` no longer raises a parameter-binding error from its - cleanup logic when the optional `ModuleName` parameter is not supplied. -- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) - `Test-PSBuildPester` now respects a Pester module that is already loaded in - the session instead of unconditionally importing the newest installed - version on top of it, which crashed with a Pester.dll version conflict when - two Pester versions were installed side by side. When no Pester is loaded, - the newest installed version (5.0.0 minimum) is imported as before, and a - loaded Pester older than 5.0.0 now produces a clear error. -- [**#138**](https://github.com/psake/PowerShellBuild/issues/138) - `Test-PSBuildPester` now reports real code coverage percentages and compares - them against `CodeCoverageThreshold` correctly. Each percentage was passed - through `[Math]::Truncate`, which collapses any fraction to zero, so the - coverage report always printed `0.00%` (or `100.00%`) and every threshold - above zero failed the build unless coverage was exactly 100%. Consumers who - set `$PSBPreference.Test.CodeCoverage.Threshold` could not use coverage - gating at all. The comparison is now strictly more permissive than before, - so a build that passed with a coverage threshold set still passes. - -## [0.8.2] 2026-07-08 - -### Fixed - -- [**#133**](https://github.com/psake/PowerShellBuild/pull/133) - `Test-PSBuildPester` now fails the build when a Pester run fails for any - reason, not only when individual tests fail. Previously the function gated - only on `FailedCount`, so a `BeforeAll`/`AfterAll` that threw or a test file - that errored during discovery left the count at zero and the build passed - despite tests never running. The gate now checks the run's aggregate - `Result` property, which Pester derives from all failure categories. - Companion to [#128](https://github.com/psake/PowerShellBuild/pull/128), - which fixes the same gap in this repository's own build file. - -## [0.8.1] 2026-06-03 - -### Fixed - -- Restore Windows PowerShell 5.1 (Desktop edition) compatibility, which regressed - in 0.8.0. `Get-PSBuildCertificate` used the PowerShell 7+-only ternary operator, - causing the file to fail to parse and the whole module to fail to import under - Windows PowerShell 5.1 — even though the manifest still declares support for it. - The ternary is replaced with an `if`/`else` expression, and the `$IsWindows` - platform guard now treats the absent automatic variable on Desktop edition as - Windows (matching the existing pattern in `Build-PSBuildUpdatableHelp`). Behavior - on PowerShell 7+ is unchanged. - -## [0.8.0] 2026-02-20 - -### Added - -- [**#92**](https://github.com/psake/PowerShellBuild/pull/92) Add Authenticode - code-signing support for PowerShell modules with three new public functions: - - `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2 objects - from certificate store, PFX files, Base64-encoded environment variables, - or pre-resolved certificate objects - - `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1, - *.psm1, *.ps1) with Authenticode signatures supporting configurable - timestamp servers and hash algorithms - - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for - tamper detection -- New build tasks for module signing pipeline: `SignModule`, `BuildCatalog`, - `SignCatalog`, `Sign` (meta-task) -- Extended `$PSBPreference.Sign` configuration section with certificate - source selection, timestamp server configuration, hash algorithm options, - and catalog generation settings - -### Fixed - -- Remove extra backticks during localization text migration. - -## [0.7.3] 2025-08-01 - -### Added - -- Add new dependencies variables to allow end user to modify which tasks are - run. -- Add localization support. - -## [0.7.2] 2025-05-21 - -### Added - -- The `$PSBPreference` variable now supports the following PlatyPS - `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options: - - `$PSBPreference.Docs.AlphabeticParamsOrder` - - `$PSBPreference.Docs.ExcludeDontShow` - - `$PSBPreference.Docs.UseFullTypeName` -- The `$PSBPreference` variable now supports the following Pester test - configuration options: - - `$PSBPreference.Test.SkipRemainingOnFailure` can be set to **None**, - **Run**, **Container** and **Block**. The default value is **None**. - - `$PSBPreference.Test.OutputVerbosity` can be set to **None**, **Normal**, - **Detailed**, and **Diagnostic**. The default value is **Detailed**. - -## [0.7.1] 2025-04-01 - -### Fixes - -- Fix a bug in `Build-PSBuildMarkdown` where a hashtable item was added twice. - -## [0.7.0] 2025-03-31 - -### Changed - -- [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules - are now explicitly created as UTF-8 files. -- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now - overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and - setting it to `$true`. -- [**#72**](https://github.com/psake/PowerShellBuild/pull/72) Loosen - dependencies by allowing them to be overwritten with - `$PSBPreference.TaskDependencies`. - -## [0.6.2] 2024-10-06 - -### Changed - -- Bump Pester to latest 5.6.1 - -### Fixed - -- [**#52**](https://github.com/psake/PowerShellBuild/pull/52) Pester object - wasn't being passed back after running tests, causing the Pester task to never - fail (via [@webtroter](https://github.com/webtroter)) -- [**#55**](https://github.com/psake/PowerShellBuild/pull/55) Add `-Module` - parameter to `Build-PSBuildUpdatableHelp` (via - [@IMJLA](https://github.com/IMJLA)) -- [**#60**](https://github.com/psake/PowerShellBuild/pull/60) Fix Windows - PowerShell compatibility in `Initialize-PSBuild` (via - [@joshooaj](https://github.com/joshooaj)) -- [**#62**](https://github.com/psake/PowerShellBuild/pull/62) Fix code coverage - output fle format not working (via - [@OpsM0nkey](https://github.com/OpsM0nkey)) - -## [0.6.1] 2021-03-14 - -### Fixed - -- Fixed bug in IB task `GenerateMarkdown` when dot sourcing precondition - -## [0.6.0] 2021-03-14 - -### Changed - -- [**#50**](https://github.com/psake/PowerShellBuild/pull/50) Invoke-Build tasks - brought inline with psake equivalents (via - [@JustinGrote](https://github.com/JustinGrote)) - -## [0.5.0] 2021-02-27 - -### Added - -- New code coverage parameters for setting output path and format: - - `$PSBPreference.Test.CodeCoverage.OutputFile` - Output file path for code - coverage results - - `$PSBPreference.Test.CodeCoverage.OutputFileFormat` - Code coverage output - format - -## [0.5.0] (beta1) - 2020-11-15 - -### Added - -- When "compiling" a monolithic PSM1, add support for both inserting - headers/footers for the entire PSM1, and for each script file. Control these - via the following new build parameters (via - [@pauby](https://github.com/pauby)) - - `$PSBPreference.Build.CompileHeader` - - `$PSBPreference.Build.CompileFooter` - - `$PSBPreference.Build.CompileScriptHeader` - - `$PSBPreference.Build.CompileScriptFooter` - -- Add ability to import project module from output directory prior to executing - Pester tests. Toggle this with `$PSBPreference.Test.ImportModule`. Defaults to - `$false`. (via [@joeypiccola](https://github.com/joeypiccola)) - -- Use `$PSBPreference.Build.CompileDirectories` to control directories who's - contents will be concatenated into the PSM1 when - `$PSBPreference.Build.CompileModule` is `$true`. Defaults to - `@('Enum', 'Classes', 'Private', 'Public')`. -- Use `$PSBPreference.Build.CopyDirectories` to control directories that will be - copied "as is" into the built module. Default is an empty array. - -### Changed - -- `$PSBPreference.Build.Exclude` now should be a list of regex expressions when - `$PSBPreference.Build.CompileModule` is `$false` (default). - -- Use Pester v5 - -### Fixed - -- Overriding `$PSBPreference.Build.OutDir` now correctly determines the final - module output directory. `$PSBPreference.Build.ModuleOutDir` is now computed - internally and **SHOULD NOT BE SET DIRECTLY**. `$PSBPreference.Build.OutDir` - will accept both relative and fully-qualified paths. - -- Before, when `$PSBPreference.Build.CompileModule` was set to `$true`, any - files listed in `$PSBPreference.Build.Exclude` weren't being excluded like - they should have been. Now, when it is `$true`, files matching regex - expressions in `$PSBPreference.Build.Exclude` will be properly excluded (via - [@pauby](https://github.com/pauby)) - -- `$PSBPreference.Help.DefaultLocale` now defaults to `en-US` on Linux since it - is not correctly determined with `Get-UICulture`. - -## [0.4.0] - 2019-08-31 - -### Changed - -- Allow using both `Credential` and `ApiKey` when publishing a module (via - [@pauby](https://github.com/pauby)) - -### Fixed - -- Don't overwrite Pester parameters when specifying `OutputPath` or - `OutputFormat` (via [@ChrisLGardner](https://github.com/ChrisLGardner)) - -## [0.3.1] - 2019-06-09 - -### Fixed - -- Don't create module page MD file. - -## [0.3.0] - 2019-04-23 - -### Fixed - -- [**#24**](https://github.com/psake/PowerShellBuild/pull/24) Fix case of - 'Public' folder when dot sourcing functions in PSM1 (via - [@pauby](https://github.com/pauby)) - -### Breaking changes - -- Refactor build properties into a single hashtable `$PSBPreference` - -### Changed - -- [**#11**](https://github.com/psake/PowerShellBuild/pull/11) The Invoke-Build - tasks are now auto-generated from the psake tasks via a converter script (via - [@JustinGrote](https://github.com/JustinGrote)) - -- [**#19**](https://github.com/psake/PowerShellBuild/pull/19) Allow the - `BHBuildOutput` environment variable defined by `BuildHelpers` to be set via - the `$PSBPreference.Build.ModuleOutDir` property of the build tasks (via - [@pauby](https://github.com/pauby)) - -## [0.2.0] - 2018-11-15 - -### Added - -- Add `Publish` task to publish the module to the defined PowerShell Repository - (PSGallery by default). - -## [0.1.1] - 2018-11-09 - -### Fixed - -- [**#4**](https://github.com/psake/PowerShellBuild/pull/4) Fix syntax for - `Analyze` task in `IB.tasks.ps1` (via - [@nightroman](https://github.com/nightroman)) - -## [0.1.0] - 2018-11-07 - -### Added - -- Initial commit - - +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). + +## Unreleased + +### 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) + 1.x. PlatyPS is also no longer a `RequiredModules` entry, so + `Install-Module PowerShellBuild` no longer installs it — the two PlatyPS + modules cannot be loaded into one process, so forcing the new one into every + session would break any consumer still holding the old one. Install it + yourself if you build help. `$PSBPreference.Docs.AlphabeticParamsOrder` is + removed, because PlatyPS 1.x always sorts parameters alphabetically and + offers no way back. Generated markdown carries the 1.x schema, though its + on-disk layout is unchanged, and now includes a module landing page that + 0.14.x never produced. Updatable help is covered separately under **Fixed**. + See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). + +- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) + **Breaking:** `Test-PSBuildScriptAnalysis` now counts PSScriptAnalyzer + `ParseError` records alongside `Error`. A file that does not parse at all + previously satisfied no threshold — not even the strictest validated value, + `Information` — so it was reported and the build passed anyway. It now fails + every threshold except `None`. See the + [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build that + passed before may now correctly fail. + +- [**#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. + +### Added + +- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) + `Test-PSBuildScriptAnalysis` accepts `Any` as a `SeverityThreshold`, failing + the build on any diagnostic record regardless of severity. `Any` was already + documented in `build.properties.ps1` but was missing from the parameter's + `ValidateSet`, so setting + `$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Any'` failed + parameter binding instead of working as documented. + +### Fixed + +- [**#169**](https://github.com/psake/PowerShellBuild/issues/169) + `Build-PSBuildUpdatableHelp` produces a help cabinet. It never could before: + it needed a module landing page that `Build-PSBuildMarkdown` did not + generate, passed an undefined variable as the cabinet source folder, and was + never given the module name — so any build that reached the + `GenerateUpdatableHelp` task failed with a parameter-binding error. + `Build-PSBuildMarkdown` now writes the landing page, and the task passes the + module name and output path it always should have. Using the task requires a + `HelpInfoUri` in your module manifest; without one it warns and produces + nothing, rather than writing a cabinet with no `HelpInfo.xml` to find it by. + See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). + +- [**#147**](https://github.com/psake/PowerShellBuild/issues/147) + `Test-PSBuildScriptAnalysis` retries the analysis when a PSScriptAnalyzer rule + crashes on an internal race + ([PSScriptAnalyzer#1538](https://github.com/PowerShell/PSScriptAnalyzer/issues/1538)), + which is unrelated to the code being analyzed and succeeds on a re-run. + Consumers who set `$ErrorActionPreference = 'Stop'` — common in a build script — + previously got a randomly red build. A crash that survives every attempt is + still surfaced, so a persistent failure behaves as it did before. + +- [**#96**](https://github.com/psake/PowerShellBuild/issues/96) + `Test-PSBuildScriptAnalysis` now fails the build when PSScriptAnalyzer + reports findings at or above the configured severity threshold. The + severity counts were computed from `$_Severity` — an undefined variable — + instead of `$_.Severity`, so all three counts were always zero and the + `Error`, `Warning`, and `Information` thresholds could never fail a build. + Script analysis reported its findings and the build passed regardless. + Because the default `FailBuildOnSeverityLevel` is `Error`, any consumer + running the `Analyze` task had a gate that only ever looked like it was + working. See the + [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build + 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. +- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) + `Test-PSBuildPester` no longer raises a parameter-binding error from its + cleanup logic when the optional `ModuleName` parameter is not supplied. +- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) + `Test-PSBuildPester` now respects a Pester module that is already loaded in + the session instead of unconditionally importing the newest installed + version on top of it, which crashed with a Pester.dll version conflict when + two Pester versions were installed side by side. When no Pester is loaded, + the newest installed version (5.0.0 minimum) is imported as before, and a + loaded Pester older than 5.0.0 now produces a clear error. +- [**#138**](https://github.com/psake/PowerShellBuild/issues/138) + `Test-PSBuildPester` now reports real code coverage percentages and compares + them against `CodeCoverageThreshold` correctly. Each percentage was passed + through `[Math]::Truncate`, which collapses any fraction to zero, so the + coverage report always printed `0.00%` (or `100.00%`) and every threshold + above zero failed the build unless coverage was exactly 100%. Consumers who + set `$PSBPreference.Test.CodeCoverage.Threshold` could not use coverage + gating at all. The comparison is now strictly more permissive than before, + so a build that passed with a coverage threshold set still passes. + +## [0.8.2] 2026-07-08 + +### Fixed + +- [**#133**](https://github.com/psake/PowerShellBuild/pull/133) + `Test-PSBuildPester` now fails the build when a Pester run fails for any + reason, not only when individual tests fail. Previously the function gated + only on `FailedCount`, so a `BeforeAll`/`AfterAll` that threw or a test file + that errored during discovery left the count at zero and the build passed + despite tests never running. The gate now checks the run's aggregate + `Result` property, which Pester derives from all failure categories. + Companion to [#128](https://github.com/psake/PowerShellBuild/pull/128), + which fixes the same gap in this repository's own build file. + +## [0.8.1] 2026-06-03 + +### Fixed + +- Restore Windows PowerShell 5.1 (Desktop edition) compatibility, which regressed + in 0.8.0. `Get-PSBuildCertificate` used the PowerShell 7+-only ternary operator, + causing the file to fail to parse and the whole module to fail to import under + Windows PowerShell 5.1 — even though the manifest still declares support for it. + The ternary is replaced with an `if`/`else` expression, and the `$IsWindows` + platform guard now treats the absent automatic variable on Desktop edition as + Windows (matching the existing pattern in `Build-PSBuildUpdatableHelp`). Behavior + on PowerShell 7+ is unchanged. + +## [0.8.0] 2026-02-20 + +### Added + +- [**#92**](https://github.com/psake/PowerShellBuild/pull/92) Add Authenticode + code-signing support for PowerShell modules with three new public functions: + - `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2 objects + from certificate store, PFX files, Base64-encoded environment variables, + or pre-resolved certificate objects + - `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1, + *.psm1, *.ps1) with Authenticode signatures supporting configurable + timestamp servers and hash algorithms + - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for + tamper detection +- New build tasks for module signing pipeline: `SignModule`, `BuildCatalog`, + `SignCatalog`, `Sign` (meta-task) +- Extended `$PSBPreference.Sign` configuration section with certificate + source selection, timestamp server configuration, hash algorithm options, + and catalog generation settings + +### Fixed + +- Remove extra backticks during localization text migration. + +## [0.7.3] 2025-08-01 + +### Added + +- Add new dependencies variables to allow end user to modify which tasks are + run. +- Add localization support. + +## [0.7.2] 2025-05-21 + +### Added + +- The `$PSBPreference` variable now supports the following PlatyPS + `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options: + - `$PSBPreference.Docs.AlphabeticParamsOrder` + - `$PSBPreference.Docs.ExcludeDontShow` + - `$PSBPreference.Docs.UseFullTypeName` +- The `$PSBPreference` variable now supports the following Pester test + configuration options: + - `$PSBPreference.Test.SkipRemainingOnFailure` can be set to **None**, + **Run**, **Container** and **Block**. The default value is **None**. + - `$PSBPreference.Test.OutputVerbosity` can be set to **None**, **Normal**, + **Detailed**, and **Diagnostic**. The default value is **Detailed**. + +## [0.7.1] 2025-04-01 + +### Fixes + +- Fix a bug in `Build-PSBuildMarkdown` where a hashtable item was added twice. + +## [0.7.0] 2025-03-31 + +### Changed + +- [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules + are now explicitly created as UTF-8 files. +- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now + overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and + setting it to `$true`. +- [**#72**](https://github.com/psake/PowerShellBuild/pull/72) Loosen + dependencies by allowing them to be overwritten with + `$PSBPreference.TaskDependencies`. + +## [0.6.2] 2024-10-06 + +### Changed + +- Bump Pester to latest 5.6.1 + +### Fixed + +- [**#52**](https://github.com/psake/PowerShellBuild/pull/52) Pester object + wasn't being passed back after running tests, causing the Pester task to never + fail (via [@webtroter](https://github.com/webtroter)) +- [**#55**](https://github.com/psake/PowerShellBuild/pull/55) Add `-Module` + parameter to `Build-PSBuildUpdatableHelp` (via + [@IMJLA](https://github.com/IMJLA)) +- [**#60**](https://github.com/psake/PowerShellBuild/pull/60) Fix Windows + PowerShell compatibility in `Initialize-PSBuild` (via + [@joshooaj](https://github.com/joshooaj)) +- [**#62**](https://github.com/psake/PowerShellBuild/pull/62) Fix code coverage + output fle format not working (via + [@OpsM0nkey](https://github.com/OpsM0nkey)) + +## [0.6.1] 2021-03-14 + +### Fixed + +- Fixed bug in IB task `GenerateMarkdown` when dot sourcing precondition + +## [0.6.0] 2021-03-14 + +### Changed + +- [**#50**](https://github.com/psake/PowerShellBuild/pull/50) Invoke-Build tasks + brought inline with psake equivalents (via + [@JustinGrote](https://github.com/JustinGrote)) + +## [0.5.0] 2021-02-27 + +### Added + +- New code coverage parameters for setting output path and format: + - `$PSBPreference.Test.CodeCoverage.OutputFile` - Output file path for code + coverage results + - `$PSBPreference.Test.CodeCoverage.OutputFileFormat` - Code coverage output + format + +## [0.5.0] (beta1) - 2020-11-15 + +### Added + +- When "compiling" a monolithic PSM1, add support for both inserting + headers/footers for the entire PSM1, and for each script file. Control these + via the following new build parameters (via + [@pauby](https://github.com/pauby)) + - `$PSBPreference.Build.CompileHeader` + - `$PSBPreference.Build.CompileFooter` + - `$PSBPreference.Build.CompileScriptHeader` + - `$PSBPreference.Build.CompileScriptFooter` + +- Add ability to import project module from output directory prior to executing + Pester tests. Toggle this with `$PSBPreference.Test.ImportModule`. Defaults to + `$false`. (via [@joeypiccola](https://github.com/joeypiccola)) + +- Use `$PSBPreference.Build.CompileDirectories` to control directories who's + contents will be concatenated into the PSM1 when + `$PSBPreference.Build.CompileModule` is `$true`. Defaults to + `@('Enum', 'Classes', 'Private', 'Public')`. +- Use `$PSBPreference.Build.CopyDirectories` to control directories that will be + copied "as is" into the built module. Default is an empty array. + +### Changed + +- `$PSBPreference.Build.Exclude` now should be a list of regex expressions when + `$PSBPreference.Build.CompileModule` is `$false` (default). + +- Use Pester v5 + +### Fixed + +- Overriding `$PSBPreference.Build.OutDir` now correctly determines the final + module output directory. `$PSBPreference.Build.ModuleOutDir` is now computed + internally and **SHOULD NOT BE SET DIRECTLY**. `$PSBPreference.Build.OutDir` + will accept both relative and fully-qualified paths. + +- Before, when `$PSBPreference.Build.CompileModule` was set to `$true`, any + files listed in `$PSBPreference.Build.Exclude` weren't being excluded like + they should have been. Now, when it is `$true`, files matching regex + expressions in `$PSBPreference.Build.Exclude` will be properly excluded (via + [@pauby](https://github.com/pauby)) + +- `$PSBPreference.Help.DefaultLocale` now defaults to `en-US` on Linux since it + is not correctly determined with `Get-UICulture`. + +## [0.4.0] - 2019-08-31 + +### Changed + +- Allow using both `Credential` and `ApiKey` when publishing a module (via + [@pauby](https://github.com/pauby)) + +### Fixed + +- Don't overwrite Pester parameters when specifying `OutputPath` or + `OutputFormat` (via [@ChrisLGardner](https://github.com/ChrisLGardner)) + +## [0.3.1] - 2019-06-09 + +### Fixed + +- Don't create module page MD file. + +## [0.3.0] - 2019-04-23 + +### Fixed + +- [**#24**](https://github.com/psake/PowerShellBuild/pull/24) Fix case of + 'Public' folder when dot sourcing functions in PSM1 (via + [@pauby](https://github.com/pauby)) + +### Breaking changes + +- Refactor build properties into a single hashtable `$PSBPreference` + +### Changed + +- [**#11**](https://github.com/psake/PowerShellBuild/pull/11) The Invoke-Build + tasks are now auto-generated from the psake tasks via a converter script (via + [@JustinGrote](https://github.com/JustinGrote)) + +- [**#19**](https://github.com/psake/PowerShellBuild/pull/19) Allow the + `BHBuildOutput` environment variable defined by `BuildHelpers` to be set via + the `$PSBPreference.Build.ModuleOutDir` property of the build tasks (via + [@pauby](https://github.com/pauby)) + +## [0.2.0] - 2018-11-15 + +### Added + +- Add `Publish` task to publish the module to the defined PowerShell Repository + (PSGallery by default). + +## [0.1.1] - 2018-11-09 + +### Fixed + +- [**#4**](https://github.com/psake/PowerShellBuild/pull/4) Fix syntax for + `Analyze` task in `IB.tasks.ps1` (via + [@nightroman](https://github.com/nightroman)) + +## [0.1.0] - 2018-11-07 + +### Added + +- Initial commit + + 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 From c5857ffb8676dbbca0d01ef464290dbe9cebe14b Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Wed, 26 Aug 2026 18:27:17 -0400 Subject: [PATCH 2/2] fix: Repair doubled carriage returns in the changelog again Same defect as 7db09e7, same cause: the insert was built by joining lines with CRLF and then converting newlines a second time, so every added line ending became \r\r\n and git saw the whole file as rewritten. Ten lines this time, turning a nine-line addition into a 736-line diff. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_012AKaM9i6NyMFDcJNeC34h5 --- CHANGELOG.md | 746 +++++++++++++++++++++++++-------------------------- 1 file changed, 373 insertions(+), 373 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index df06aaa..5da6b45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,373 +1,373 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](http://keepachangelog.com/) -and this project adheres to [Semantic Versioning](http://semver.org/). - -## Unreleased - -### 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) - 1.x. PlatyPS is also no longer a `RequiredModules` entry, so - `Install-Module PowerShellBuild` no longer installs it — the two PlatyPS - modules cannot be loaded into one process, so forcing the new one into every - session would break any consumer still holding the old one. Install it - yourself if you build help. `$PSBPreference.Docs.AlphabeticParamsOrder` is - removed, because PlatyPS 1.x always sorts parameters alphabetically and - offers no way back. Generated markdown carries the 1.x schema, though its - on-disk layout is unchanged, and now includes a module landing page that - 0.14.x never produced. Updatable help is covered separately under **Fixed**. - See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). - -- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) - **Breaking:** `Test-PSBuildScriptAnalysis` now counts PSScriptAnalyzer - `ParseError` records alongside `Error`. A file that does not parse at all - previously satisfied no threshold — not even the strictest validated value, - `Information` — so it was reported and the build passed anyway. It now fails - every threshold except `None`. See the - [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build that - passed before may now correctly fail. - -- [**#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. - -### Added - -- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) - `Test-PSBuildScriptAnalysis` accepts `Any` as a `SeverityThreshold`, failing - the build on any diagnostic record regardless of severity. `Any` was already - documented in `build.properties.ps1` but was missing from the parameter's - `ValidateSet`, so setting - `$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Any'` failed - parameter binding instead of working as documented. - -### Fixed - -- [**#169**](https://github.com/psake/PowerShellBuild/issues/169) - `Build-PSBuildUpdatableHelp` produces a help cabinet. It never could before: - it needed a module landing page that `Build-PSBuildMarkdown` did not - generate, passed an undefined variable as the cabinet source folder, and was - never given the module name — so any build that reached the - `GenerateUpdatableHelp` task failed with a parameter-binding error. - `Build-PSBuildMarkdown` now writes the landing page, and the task passes the - module name and output path it always should have. Using the task requires a - `HelpInfoUri` in your module manifest; without one it warns and produces - nothing, rather than writing a cabinet with no `HelpInfo.xml` to find it by. - See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). - -- [**#147**](https://github.com/psake/PowerShellBuild/issues/147) - `Test-PSBuildScriptAnalysis` retries the analysis when a PSScriptAnalyzer rule - crashes on an internal race - ([PSScriptAnalyzer#1538](https://github.com/PowerShell/PSScriptAnalyzer/issues/1538)), - which is unrelated to the code being analyzed and succeeds on a re-run. - Consumers who set `$ErrorActionPreference = 'Stop'` — common in a build script — - previously got a randomly red build. A crash that survives every attempt is - still surfaced, so a persistent failure behaves as it did before. - -- [**#96**](https://github.com/psake/PowerShellBuild/issues/96) - `Test-PSBuildScriptAnalysis` now fails the build when PSScriptAnalyzer - reports findings at or above the configured severity threshold. The - severity counts were computed from `$_Severity` — an undefined variable — - instead of `$_.Severity`, so all three counts were always zero and the - `Error`, `Warning`, and `Information` thresholds could never fail a build. - Script analysis reported its findings and the build passed regardless. - Because the default `FailBuildOnSeverityLevel` is `Error`, any consumer - running the `Analyze` task had a gate that only ever looked like it was - working. See the - [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build - 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. -- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) - `Test-PSBuildPester` no longer raises a parameter-binding error from its - cleanup logic when the optional `ModuleName` parameter is not supplied. -- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) - `Test-PSBuildPester` now respects a Pester module that is already loaded in - the session instead of unconditionally importing the newest installed - version on top of it, which crashed with a Pester.dll version conflict when - two Pester versions were installed side by side. When no Pester is loaded, - the newest installed version (5.0.0 minimum) is imported as before, and a - loaded Pester older than 5.0.0 now produces a clear error. -- [**#138**](https://github.com/psake/PowerShellBuild/issues/138) - `Test-PSBuildPester` now reports real code coverage percentages and compares - them against `CodeCoverageThreshold` correctly. Each percentage was passed - through `[Math]::Truncate`, which collapses any fraction to zero, so the - coverage report always printed `0.00%` (or `100.00%`) and every threshold - above zero failed the build unless coverage was exactly 100%. Consumers who - set `$PSBPreference.Test.CodeCoverage.Threshold` could not use coverage - gating at all. The comparison is now strictly more permissive than before, - so a build that passed with a coverage threshold set still passes. - -## [0.8.2] 2026-07-08 - -### Fixed - -- [**#133**](https://github.com/psake/PowerShellBuild/pull/133) - `Test-PSBuildPester` now fails the build when a Pester run fails for any - reason, not only when individual tests fail. Previously the function gated - only on `FailedCount`, so a `BeforeAll`/`AfterAll` that threw or a test file - that errored during discovery left the count at zero and the build passed - despite tests never running. The gate now checks the run's aggregate - `Result` property, which Pester derives from all failure categories. - Companion to [#128](https://github.com/psake/PowerShellBuild/pull/128), - which fixes the same gap in this repository's own build file. - -## [0.8.1] 2026-06-03 - -### Fixed - -- Restore Windows PowerShell 5.1 (Desktop edition) compatibility, which regressed - in 0.8.0. `Get-PSBuildCertificate` used the PowerShell 7+-only ternary operator, - causing the file to fail to parse and the whole module to fail to import under - Windows PowerShell 5.1 — even though the manifest still declares support for it. - The ternary is replaced with an `if`/`else` expression, and the `$IsWindows` - platform guard now treats the absent automatic variable on Desktop edition as - Windows (matching the existing pattern in `Build-PSBuildUpdatableHelp`). Behavior - on PowerShell 7+ is unchanged. - -## [0.8.0] 2026-02-20 - -### Added - -- [**#92**](https://github.com/psake/PowerShellBuild/pull/92) Add Authenticode - code-signing support for PowerShell modules with three new public functions: - - `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2 objects - from certificate store, PFX files, Base64-encoded environment variables, - or pre-resolved certificate objects - - `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1, - *.psm1, *.ps1) with Authenticode signatures supporting configurable - timestamp servers and hash algorithms - - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for - tamper detection -- New build tasks for module signing pipeline: `SignModule`, `BuildCatalog`, - `SignCatalog`, `Sign` (meta-task) -- Extended `$PSBPreference.Sign` configuration section with certificate - source selection, timestamp server configuration, hash algorithm options, - and catalog generation settings - -### Fixed - -- Remove extra backticks during localization text migration. - -## [0.7.3] 2025-08-01 - -### Added - -- Add new dependencies variables to allow end user to modify which tasks are - run. -- Add localization support. - -## [0.7.2] 2025-05-21 - -### Added - -- The `$PSBPreference` variable now supports the following PlatyPS - `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options: - - `$PSBPreference.Docs.AlphabeticParamsOrder` - - `$PSBPreference.Docs.ExcludeDontShow` - - `$PSBPreference.Docs.UseFullTypeName` -- The `$PSBPreference` variable now supports the following Pester test - configuration options: - - `$PSBPreference.Test.SkipRemainingOnFailure` can be set to **None**, - **Run**, **Container** and **Block**. The default value is **None**. - - `$PSBPreference.Test.OutputVerbosity` can be set to **None**, **Normal**, - **Detailed**, and **Diagnostic**. The default value is **Detailed**. - -## [0.7.1] 2025-04-01 - -### Fixes - -- Fix a bug in `Build-PSBuildMarkdown` where a hashtable item was added twice. - -## [0.7.0] 2025-03-31 - -### Changed - -- [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules - are now explicitly created as UTF-8 files. -- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now - overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and - setting it to `$true`. -- [**#72**](https://github.com/psake/PowerShellBuild/pull/72) Loosen - dependencies by allowing them to be overwritten with - `$PSBPreference.TaskDependencies`. - -## [0.6.2] 2024-10-06 - -### Changed - -- Bump Pester to latest 5.6.1 - -### Fixed - -- [**#52**](https://github.com/psake/PowerShellBuild/pull/52) Pester object - wasn't being passed back after running tests, causing the Pester task to never - fail (via [@webtroter](https://github.com/webtroter)) -- [**#55**](https://github.com/psake/PowerShellBuild/pull/55) Add `-Module` - parameter to `Build-PSBuildUpdatableHelp` (via - [@IMJLA](https://github.com/IMJLA)) -- [**#60**](https://github.com/psake/PowerShellBuild/pull/60) Fix Windows - PowerShell compatibility in `Initialize-PSBuild` (via - [@joshooaj](https://github.com/joshooaj)) -- [**#62**](https://github.com/psake/PowerShellBuild/pull/62) Fix code coverage - output fle format not working (via - [@OpsM0nkey](https://github.com/OpsM0nkey)) - -## [0.6.1] 2021-03-14 - -### Fixed - -- Fixed bug in IB task `GenerateMarkdown` when dot sourcing precondition - -## [0.6.0] 2021-03-14 - -### Changed - -- [**#50**](https://github.com/psake/PowerShellBuild/pull/50) Invoke-Build tasks - brought inline with psake equivalents (via - [@JustinGrote](https://github.com/JustinGrote)) - -## [0.5.0] 2021-02-27 - -### Added - -- New code coverage parameters for setting output path and format: - - `$PSBPreference.Test.CodeCoverage.OutputFile` - Output file path for code - coverage results - - `$PSBPreference.Test.CodeCoverage.OutputFileFormat` - Code coverage output - format - -## [0.5.0] (beta1) - 2020-11-15 - -### Added - -- When "compiling" a monolithic PSM1, add support for both inserting - headers/footers for the entire PSM1, and for each script file. Control these - via the following new build parameters (via - [@pauby](https://github.com/pauby)) - - `$PSBPreference.Build.CompileHeader` - - `$PSBPreference.Build.CompileFooter` - - `$PSBPreference.Build.CompileScriptHeader` - - `$PSBPreference.Build.CompileScriptFooter` - -- Add ability to import project module from output directory prior to executing - Pester tests. Toggle this with `$PSBPreference.Test.ImportModule`. Defaults to - `$false`. (via [@joeypiccola](https://github.com/joeypiccola)) - -- Use `$PSBPreference.Build.CompileDirectories` to control directories who's - contents will be concatenated into the PSM1 when - `$PSBPreference.Build.CompileModule` is `$true`. Defaults to - `@('Enum', 'Classes', 'Private', 'Public')`. -- Use `$PSBPreference.Build.CopyDirectories` to control directories that will be - copied "as is" into the built module. Default is an empty array. - -### Changed - -- `$PSBPreference.Build.Exclude` now should be a list of regex expressions when - `$PSBPreference.Build.CompileModule` is `$false` (default). - -- Use Pester v5 - -### Fixed - -- Overriding `$PSBPreference.Build.OutDir` now correctly determines the final - module output directory. `$PSBPreference.Build.ModuleOutDir` is now computed - internally and **SHOULD NOT BE SET DIRECTLY**. `$PSBPreference.Build.OutDir` - will accept both relative and fully-qualified paths. - -- Before, when `$PSBPreference.Build.CompileModule` was set to `$true`, any - files listed in `$PSBPreference.Build.Exclude` weren't being excluded like - they should have been. Now, when it is `$true`, files matching regex - expressions in `$PSBPreference.Build.Exclude` will be properly excluded (via - [@pauby](https://github.com/pauby)) - -- `$PSBPreference.Help.DefaultLocale` now defaults to `en-US` on Linux since it - is not correctly determined with `Get-UICulture`. - -## [0.4.0] - 2019-08-31 - -### Changed - -- Allow using both `Credential` and `ApiKey` when publishing a module (via - [@pauby](https://github.com/pauby)) - -### Fixed - -- Don't overwrite Pester parameters when specifying `OutputPath` or - `OutputFormat` (via [@ChrisLGardner](https://github.com/ChrisLGardner)) - -## [0.3.1] - 2019-06-09 - -### Fixed - -- Don't create module page MD file. - -## [0.3.0] - 2019-04-23 - -### Fixed - -- [**#24**](https://github.com/psake/PowerShellBuild/pull/24) Fix case of - 'Public' folder when dot sourcing functions in PSM1 (via - [@pauby](https://github.com/pauby)) - -### Breaking changes - -- Refactor build properties into a single hashtable `$PSBPreference` - -### Changed - -- [**#11**](https://github.com/psake/PowerShellBuild/pull/11) The Invoke-Build - tasks are now auto-generated from the psake tasks via a converter script (via - [@JustinGrote](https://github.com/JustinGrote)) - -- [**#19**](https://github.com/psake/PowerShellBuild/pull/19) Allow the - `BHBuildOutput` environment variable defined by `BuildHelpers` to be set via - the `$PSBPreference.Build.ModuleOutDir` property of the build tasks (via - [@pauby](https://github.com/pauby)) - -## [0.2.0] - 2018-11-15 - -### Added - -- Add `Publish` task to publish the module to the defined PowerShell Repository - (PSGallery by default). - -## [0.1.1] - 2018-11-09 - -### Fixed - -- [**#4**](https://github.com/psake/PowerShellBuild/pull/4) Fix syntax for - `Analyze` task in `IB.tasks.ps1` (via - [@nightroman](https://github.com/nightroman)) - -## [0.1.0] - 2018-11-07 - -### Added - -- Initial commit - - +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). + +## Unreleased + +### 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) + 1.x. PlatyPS is also no longer a `RequiredModules` entry, so + `Install-Module PowerShellBuild` no longer installs it — the two PlatyPS + modules cannot be loaded into one process, so forcing the new one into every + session would break any consumer still holding the old one. Install it + yourself if you build help. `$PSBPreference.Docs.AlphabeticParamsOrder` is + removed, because PlatyPS 1.x always sorts parameters alphabetically and + offers no way back. Generated markdown carries the 1.x schema, though its + on-disk layout is unchanged, and now includes a module landing page that + 0.14.x never produced. Updatable help is covered separately under **Fixed**. + See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). + +- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) + **Breaking:** `Test-PSBuildScriptAnalysis` now counts PSScriptAnalyzer + `ParseError` records alongside `Error`. A file that does not parse at all + previously satisfied no threshold — not even the strictest validated value, + `Information` — so it was reported and the build passed anyway. It now fails + every threshold except `None`. See the + [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build that + passed before may now correctly fail. + +- [**#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. + +### Added + +- [**#144**](https://github.com/psake/PowerShellBuild/issues/144) + `Test-PSBuildScriptAnalysis` accepts `Any` as a `SeverityThreshold`, failing + the build on any diagnostic record regardless of severity. `Any` was already + documented in `build.properties.ps1` but was missing from the parameter's + `ValidateSet`, so setting + `$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Any'` failed + parameter binding instead of working as documented. + +### Fixed + +- [**#169**](https://github.com/psake/PowerShellBuild/issues/169) + `Build-PSBuildUpdatableHelp` produces a help cabinet. It never could before: + it needed a module landing page that `Build-PSBuildMarkdown` did not + generate, passed an undefined variable as the cabinet source folder, and was + never given the module name — so any build that reached the + `GenerateUpdatableHelp` task failed with a parameter-binding error. + `Build-PSBuildMarkdown` now writes the landing page, and the task passes the + module name and output path it always should have. Using the task requires a + `HelpInfoUri` in your module manifest; without one it warns and produces + nothing, rather than writing a cabinet with no `HelpInfo.xml` to find it by. + See the [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md). + +- [**#147**](https://github.com/psake/PowerShellBuild/issues/147) + `Test-PSBuildScriptAnalysis` retries the analysis when a PSScriptAnalyzer rule + crashes on an internal race + ([PSScriptAnalyzer#1538](https://github.com/PowerShell/PSScriptAnalyzer/issues/1538)), + which is unrelated to the code being analyzed and succeeds on a re-run. + Consumers who set `$ErrorActionPreference = 'Stop'` — common in a build script — + previously got a randomly red build. A crash that survives every attempt is + still surfaced, so a persistent failure behaves as it did before. + +- [**#96**](https://github.com/psake/PowerShellBuild/issues/96) + `Test-PSBuildScriptAnalysis` now fails the build when PSScriptAnalyzer + reports findings at or above the configured severity threshold. The + severity counts were computed from `$_Severity` — an undefined variable — + instead of `$_.Severity`, so all three counts were always zero and the + `Error`, `Warning`, and `Information` thresholds could never fail a build. + Script analysis reported its findings and the build passed regardless. + Because the default `FailBuildOnSeverityLevel` is `Error`, any consumer + running the `Analyze` task had a gate that only ever looked like it was + working. See the + [v0.8 → v1.0 migration guide](docs/migration-v0.8-to-v1.0.md) — a build + 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. +- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) + `Test-PSBuildPester` no longer raises a parameter-binding error from its + cleanup logic when the optional `ModuleName` parameter is not supplied. +- [**#102**](https://github.com/psake/PowerShellBuild/issues/102) + `Test-PSBuildPester` now respects a Pester module that is already loaded in + the session instead of unconditionally importing the newest installed + version on top of it, which crashed with a Pester.dll version conflict when + two Pester versions were installed side by side. When no Pester is loaded, + the newest installed version (5.0.0 minimum) is imported as before, and a + loaded Pester older than 5.0.0 now produces a clear error. +- [**#138**](https://github.com/psake/PowerShellBuild/issues/138) + `Test-PSBuildPester` now reports real code coverage percentages and compares + them against `CodeCoverageThreshold` correctly. Each percentage was passed + through `[Math]::Truncate`, which collapses any fraction to zero, so the + coverage report always printed `0.00%` (or `100.00%`) and every threshold + above zero failed the build unless coverage was exactly 100%. Consumers who + set `$PSBPreference.Test.CodeCoverage.Threshold` could not use coverage + gating at all. The comparison is now strictly more permissive than before, + so a build that passed with a coverage threshold set still passes. + +## [0.8.2] 2026-07-08 + +### Fixed + +- [**#133**](https://github.com/psake/PowerShellBuild/pull/133) + `Test-PSBuildPester` now fails the build when a Pester run fails for any + reason, not only when individual tests fail. Previously the function gated + only on `FailedCount`, so a `BeforeAll`/`AfterAll` that threw or a test file + that errored during discovery left the count at zero and the build passed + despite tests never running. The gate now checks the run's aggregate + `Result` property, which Pester derives from all failure categories. + Companion to [#128](https://github.com/psake/PowerShellBuild/pull/128), + which fixes the same gap in this repository's own build file. + +## [0.8.1] 2026-06-03 + +### Fixed + +- Restore Windows PowerShell 5.1 (Desktop edition) compatibility, which regressed + in 0.8.0. `Get-PSBuildCertificate` used the PowerShell 7+-only ternary operator, + causing the file to fail to parse and the whole module to fail to import under + Windows PowerShell 5.1 — even though the manifest still declares support for it. + The ternary is replaced with an `if`/`else` expression, and the `$IsWindows` + platform guard now treats the absent automatic variable on Desktop edition as + Windows (matching the existing pattern in `Build-PSBuildUpdatableHelp`). Behavior + on PowerShell 7+ is unchanged. + +## [0.8.0] 2026-02-20 + +### Added + +- [**#92**](https://github.com/psake/PowerShellBuild/pull/92) Add Authenticode + code-signing support for PowerShell modules with three new public functions: + - `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2 objects + from certificate store, PFX files, Base64-encoded environment variables, + or pre-resolved certificate objects + - `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1, + *.psm1, *.ps1) with Authenticode signatures supporting configurable + timestamp servers and hash algorithms + - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for + tamper detection +- New build tasks for module signing pipeline: `SignModule`, `BuildCatalog`, + `SignCatalog`, `Sign` (meta-task) +- Extended `$PSBPreference.Sign` configuration section with certificate + source selection, timestamp server configuration, hash algorithm options, + and catalog generation settings + +### Fixed + +- Remove extra backticks during localization text migration. + +## [0.7.3] 2025-08-01 + +### Added + +- Add new dependencies variables to allow end user to modify which tasks are + run. +- Add localization support. + +## [0.7.2] 2025-05-21 + +### Added + +- The `$PSBPreference` variable now supports the following PlatyPS + `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options: + - `$PSBPreference.Docs.AlphabeticParamsOrder` + - `$PSBPreference.Docs.ExcludeDontShow` + - `$PSBPreference.Docs.UseFullTypeName` +- The `$PSBPreference` variable now supports the following Pester test + configuration options: + - `$PSBPreference.Test.SkipRemainingOnFailure` can be set to **None**, + **Run**, **Container** and **Block**. The default value is **None**. + - `$PSBPreference.Test.OutputVerbosity` can be set to **None**, **Normal**, + **Detailed**, and **Diagnostic**. The default value is **Detailed**. + +## [0.7.1] 2025-04-01 + +### Fixes + +- Fix a bug in `Build-PSBuildMarkdown` where a hashtable item was added twice. + +## [0.7.0] 2025-03-31 + +### Changed + +- [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules + are now explicitly created as UTF-8 files. +- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now + overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and + setting it to `$true`. +- [**#72**](https://github.com/psake/PowerShellBuild/pull/72) Loosen + dependencies by allowing them to be overwritten with + `$PSBPreference.TaskDependencies`. + +## [0.6.2] 2024-10-06 + +### Changed + +- Bump Pester to latest 5.6.1 + +### Fixed + +- [**#52**](https://github.com/psake/PowerShellBuild/pull/52) Pester object + wasn't being passed back after running tests, causing the Pester task to never + fail (via [@webtroter](https://github.com/webtroter)) +- [**#55**](https://github.com/psake/PowerShellBuild/pull/55) Add `-Module` + parameter to `Build-PSBuildUpdatableHelp` (via + [@IMJLA](https://github.com/IMJLA)) +- [**#60**](https://github.com/psake/PowerShellBuild/pull/60) Fix Windows + PowerShell compatibility in `Initialize-PSBuild` (via + [@joshooaj](https://github.com/joshooaj)) +- [**#62**](https://github.com/psake/PowerShellBuild/pull/62) Fix code coverage + output fle format not working (via + [@OpsM0nkey](https://github.com/OpsM0nkey)) + +## [0.6.1] 2021-03-14 + +### Fixed + +- Fixed bug in IB task `GenerateMarkdown` when dot sourcing precondition + +## [0.6.0] 2021-03-14 + +### Changed + +- [**#50**](https://github.com/psake/PowerShellBuild/pull/50) Invoke-Build tasks + brought inline with psake equivalents (via + [@JustinGrote](https://github.com/JustinGrote)) + +## [0.5.0] 2021-02-27 + +### Added + +- New code coverage parameters for setting output path and format: + - `$PSBPreference.Test.CodeCoverage.OutputFile` - Output file path for code + coverage results + - `$PSBPreference.Test.CodeCoverage.OutputFileFormat` - Code coverage output + format + +## [0.5.0] (beta1) - 2020-11-15 + +### Added + +- When "compiling" a monolithic PSM1, add support for both inserting + headers/footers for the entire PSM1, and for each script file. Control these + via the following new build parameters (via + [@pauby](https://github.com/pauby)) + - `$PSBPreference.Build.CompileHeader` + - `$PSBPreference.Build.CompileFooter` + - `$PSBPreference.Build.CompileScriptHeader` + - `$PSBPreference.Build.CompileScriptFooter` + +- Add ability to import project module from output directory prior to executing + Pester tests. Toggle this with `$PSBPreference.Test.ImportModule`. Defaults to + `$false`. (via [@joeypiccola](https://github.com/joeypiccola)) + +- Use `$PSBPreference.Build.CompileDirectories` to control directories who's + contents will be concatenated into the PSM1 when + `$PSBPreference.Build.CompileModule` is `$true`. Defaults to + `@('Enum', 'Classes', 'Private', 'Public')`. +- Use `$PSBPreference.Build.CopyDirectories` to control directories that will be + copied "as is" into the built module. Default is an empty array. + +### Changed + +- `$PSBPreference.Build.Exclude` now should be a list of regex expressions when + `$PSBPreference.Build.CompileModule` is `$false` (default). + +- Use Pester v5 + +### Fixed + +- Overriding `$PSBPreference.Build.OutDir` now correctly determines the final + module output directory. `$PSBPreference.Build.ModuleOutDir` is now computed + internally and **SHOULD NOT BE SET DIRECTLY**. `$PSBPreference.Build.OutDir` + will accept both relative and fully-qualified paths. + +- Before, when `$PSBPreference.Build.CompileModule` was set to `$true`, any + files listed in `$PSBPreference.Build.Exclude` weren't being excluded like + they should have been. Now, when it is `$true`, files matching regex + expressions in `$PSBPreference.Build.Exclude` will be properly excluded (via + [@pauby](https://github.com/pauby)) + +- `$PSBPreference.Help.DefaultLocale` now defaults to `en-US` on Linux since it + is not correctly determined with `Get-UICulture`. + +## [0.4.0] - 2019-08-31 + +### Changed + +- Allow using both `Credential` and `ApiKey` when publishing a module (via + [@pauby](https://github.com/pauby)) + +### Fixed + +- Don't overwrite Pester parameters when specifying `OutputPath` or + `OutputFormat` (via [@ChrisLGardner](https://github.com/ChrisLGardner)) + +## [0.3.1] - 2019-06-09 + +### Fixed + +- Don't create module page MD file. + +## [0.3.0] - 2019-04-23 + +### Fixed + +- [**#24**](https://github.com/psake/PowerShellBuild/pull/24) Fix case of + 'Public' folder when dot sourcing functions in PSM1 (via + [@pauby](https://github.com/pauby)) + +### Breaking changes + +- Refactor build properties into a single hashtable `$PSBPreference` + +### Changed + +- [**#11**](https://github.com/psake/PowerShellBuild/pull/11) The Invoke-Build + tasks are now auto-generated from the psake tasks via a converter script (via + [@JustinGrote](https://github.com/JustinGrote)) + +- [**#19**](https://github.com/psake/PowerShellBuild/pull/19) Allow the + `BHBuildOutput` environment variable defined by `BuildHelpers` to be set via + the `$PSBPreference.Build.ModuleOutDir` property of the build tasks (via + [@pauby](https://github.com/pauby)) + +## [0.2.0] - 2018-11-15 + +### Added + +- Add `Publish` task to publish the module to the defined PowerShell Repository + (PSGallery by default). + +## [0.1.1] - 2018-11-09 + +### Fixed + +- [**#4**](https://github.com/psake/PowerShellBuild/pull/4) Fix syntax for + `Analyze` task in `IB.tasks.ps1` (via + [@nightroman](https://github.com/nightroman)) + +## [0.1.0] - 2018-11-07 + +### Added + +- Initial commit + +