feat: Migrate updatable help to the PlatyPS 1.x cabinet pipeline - #176
Merged
Conversation
Closes #152. Closes #101. Closes #169. Part of #105, Phase 2 of #120. Build-PSBuildUpdatableHelp produces a cabinet, its zip, and a HelpInfo.xml. It never could before. #169 recorded three defects, and every one of them alone was fatal: the module landing page New-ExternalHelpCab needs was never generated, $moduleOutDir was undefined anywhere in the codebase, and the task passed no -Module so the parameter defaulted from an unset caller-scope variable. New-HelpCabinetFile maps cleanly onto the old call -- CabinetFilesFolder / MarkdownModuleFile / OutputFolder against CabFilesFolder / LandingPagePath / OutputFolder -- so the port itself was small. The defects were the work. Build-PSBuildMarkdown now passes -WithModulePage. #173 deliberately did not, because 0.14.x produced no landing page and adding one puts a new file in every consumer's docs tree; the cabinet needs it, so it lands here with its migration-guide entry. It stays filtered out of the MAML export, where a module page aborts the whole batch (PowerShell/platyPS#862). The function refuses when the manifest declares no HelpInfoUri. Measured: without one, New-HelpCabinetFile writes the cabinet and the zip and then fails before the HelpInfo.xml that Update-Help resolves them through, leaving output that looks complete and cannot be used. Both test fixtures gained a placeholder URI for the same reason. Defect 3 lived in the task rather than the function, so a function-level test could never catch it: build.tests.ps1 now runs the GenerateUpdatableHelp task itself through the child-process pattern the other build contexts use, and asserts both artifacts. That was Copilot's point on #170 and it was right. Also corrects the header of Build-PSBuildHelp.tests.ps1, which claimed nothing observed these functions. build.tests.ps1 has covered GenerateMarkdown and GenerateMAML end to end all along. Suite: 470 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012AKaM9i6NyMFDcJNeC34h5
Test Results 4 files ± 0 740 suites +16 4m 56s ⏱️ +55s Results for commit 2e6e872. ± Comparison against base commit 48366eb. This pull request removes 2 and adds 12 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
The landing page was never refreshed after the first build. The refresh pass filters to CommandHelp documents, which excludes it, and the move loop then skipped it because a copy already existed -- under a comment claiming it had "already refreshed above", which was true of command help and false of the module page. It is now always replaced. The review's stated consequence does not hold, and it is worth recording why. It argued that a stale page freezes HelpContentVersion so Update-Help stops fetching after a version bump. Measured: "Help Version" is a constant 1.0.0.0 that New-MarkdownCommandHelp does not derive from ModuleVersion -- the fixture is 0.1.0 and its page still reads 1.0.0.0 -- so a version bump never moved it either way. Update-MarkdownModuleFile is no help: it leaves the version alone and rewrites the body, losing prose. What does go stale is the module GUID, which stamps the cabinet file name, and the command index, which is the page's whole body. Both justify always replacing it, and the test asserts the GUID case because that one silently misnames the cabinet. Also from the review, all correct: - OutputPath was cleared before anything was known to be writable, so a run where every locale hit a guard deleted the previous cabinet and replaced it with nothing. The work is now resolved first and the wipe skipped when there is none, matching the refuse-before-producing posture of the guards above it. - The changelog's #105 entry still said updatable help "warns and returns until the cabinet pipeline migrates in #152" -- in the release that is #152. Rewritten, with updatable help left to the Fixed entry. - Unreleased carried two "### Fixed" headings. Merged. - Three new $*Params variables contradicted shorthand.instructions.md and the test file added alongside them. Renamed to Parameters. Suite: 471 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012AKaM9i6NyMFDcJNeC34h5
This was referenced Aug 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #152. Closes #101. Closes #169. Part of #105 (PlatyPS migration), Phase 2 of #120.
The last link in the PlatyPS chain.
#157(1.0.0-preview1) is unblocked once this lands.Build-PSBuildUpdatableHelpnow works, which it never didThe port itself was small.
New-HelpCabinetFilemaps cleanly onto the old call:New-ExternalHelpCabNew-HelpCabinetFileCabFilesFolderCabinetFilesFolderLandingPagePathMarkdownModuleFileOutputFolderOutputFolderThe three defects in #169 were the actual work, and any one of them alone was fatal:
$moduleOutDirwas undefined anywhere in the module or the psake file, and-Module, so it defaulted from an unset caller-scope variable.So there was no working behavior to port — which is why this ticket ran well past "swap one
cmdlet".
It refuses rather than half-producing
New-HelpCabinetFilerequires aHelpInfoUri. Measured with and without one:Without the URI you get cabinet files and no
HelpInfo.xml— which is the fileUpdate-Helpresolves them through. That is output that looks complete and cannot be used, so the function
checks the manifest first and produces nothing. Neither of this repository's fixtures had a
HelpInfoUri; both gained a placeholder, and there is a migration-guide entry telling consumersto add a real one.
The landing page
Build-PSBuildMarkdownnow passes-WithModulePage. #173 deliberately did not: 0.14.x producedno landing page, and generating one puts a new file in every consumer's docs tree. The cabinet
needs it — it carries the module GUID, locale, and help version — so the change belongs here, with
its own migration entry.
It stays excluded from MAML generation. A module page in an export batch aborts the entire export
and writes nothing (PowerShell/platyPS#862,
filed from this work), and the existing
Measure-PlatyPSMarkdownfilter already handles it.The task-level regression, which is the part that matters
Defect 3 lived in the wiring, not the function. Every function-level fix could pass while
GenerateUpdatableHelpstayed broken, because the task supplied neither the module name nor themodule output path — and the unit tests pass
-Moduleexplicitly, so by construction they cannotcatch it. That was Copilot's argument on #170 and it was correct.
tests/build.tests.ps1now runs the task, through the same child-process pattern the otherbuild contexts use, since psake cannot nest:
Verification
Build-PSBuildHelp.tests.ps1is skipped now<Module>_<GUID>_<locale>_HelpContent.cabHelpInfoUriwrites nothing, not a partial cabinet$IsWindows -or $null -eq $IsWindows, so Windows PowerShell 5.1takes the Windows branch
Also in here
The header of
Build-PSBuildHelp.tests.ps1claimed nothing observed these functions. That waswrong and I put it on #120 too.
build.tests.ps1has been exercisingGenerateMarkdownandGenerateMAMLend to end all along viatests/TestModule. Header corrected; the #120 row stillneeds the same fix.