fix: Correct three defects in how a module is staged - #225
Open
tablackburn wants to merge 3 commits into
Open
Conversation
PSBuildTestFixture had no culture directory, no .psd1 below its root and no about topic, so the staging tests were structurally incapable of observing #210, #211 or #212. All three have been reachable since 2018 with the suite green. Adds en-US/Messages.psd1 and a hand-written en-US/about_PSBuildTestFixture.help.txt and asserts both in the fixture layout test. Narrows one assertion in Build-PSBuildHelp.tests.ps1 as a consequence. Microsoft.PowerShell.PlatyPS 1.x warns "File '' is not a valid help file type" for every file in the module's locale directory that is not the generated MAML, a hand-written about topic included, and with an empty name in its own message. That is upstream behavior about what the module ships, not the docs-tree defect the context pins, so it now asserts that no landing-page warning is reported rather than that no warning at all is. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
Sequenced #211, #210, #212, because each one is only visible once the one before it is fixed. #211: the loose-file glob used -Path $Path with -Include and -Depth 1, so it recursed one level and copied en-US/Messages.psd1 flat into the output root, where nothing reads it. Both halves of the fix are required: the trailing wildcard alone still matches the culture directory, and dropping -Depth alone matches nothing at all, because without recursion -Include filters against the leaf of -Path. On Windows PowerShell 5.1, -Depth with -Include degrades to a full -Recurse, so files at any depth were flattened into the root and the contents of a package depended on which host built it. The same pattern in the readme discovery in psakeFile.ps1 and IB.tasks.ps1 is fixed with it. #210: compile mode staged the loose root files and CopyDirectories and nothing else, so a hand-written about topic never reached the output unless CopyDirectories happened to name the culture directory. Compile mode now stages a source culture directory on its own. Get-PSBuildHelpLocale answers which directories are cultures, but deliberately over-reports -- 'bin' is Bini and 'ps' is Pashto -- so staging is decided by content: an about topic, MAML help, or localized data. #212: the two modes disagreed about whether a source about topic or the readme won, by accident of statement ordering. A source about topic now wins in both, with a warning, because ConvertReadMeToAboutHelp performs no conversion -- it is a plain copy of the Markdown, which is not a conformant about topic. The guard tests the source about *file*, which is narrower than the culture *directory* guard #207 removed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
One changelog entry per issue, and migration entries for the two changes a consumer can see on upgrade: the output root loses a stray copy of a culture directory's .psd1 and the readme now has to be at the project root to be found (#211), and a hand-written about topic now wins over ConvertReadMeToAboutHelp with a warning (#212). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
tablackburn
force-pushed
the
fix/210-211-212-staging
branch
from
August 28, 2026 22:10
8aa718c to
f97dac2
Compare
Test Results 4 files ± 0 909 suites +20 2m 9s ⏱️ -18s Results for commit f97dac2. ± Comparison against base commit 3ea9e82. This pull request removes 2 and adds 19 tests. Note that renamed tests count towards both. |
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.
Summary
Fixes three defects in
Build-PSBuildModule's staging logic, sequenced #211 → #210 → #212because each is only visible once the one before it is fixed. Closes #210, #211, #212.
-Path $Pathwith-Includeand-Depth 1, so itrecursed one level and copied
en-US/Messages.psd1flat into the output root. Bothhalves of the fix are required:
$Path\*alone still matches the culture directory, anddropping
-Depthalone matches nothing, because without recursion-Includefiltersagainst the leaf of
-Path. The same pattern in the readme discovery inpsakeFile.ps1and
IB.tasks.ps1is fixed with it.CopyDirectoriesand nothing else, so ahand-written about topic reached the output only if
CopyDirectorieshappened to name theculture directory. Compile mode now stages a source culture directory on its own.
by accident of statement ordering. Source wins in both now, with a warning:
ConvertReadMeToAboutHelpperforms no conversion, so "readme wins" replaces conformanthelp with raw Markdown.
Host-dependence, measured
-Depthwith-Includedegrades to a full-Recurseon Windows PowerShell 5.1. Same glob,same tree (
tests/), two hosts:Readme discovery, on 5.1: before,
tests/TestModule/README.mdcame back first andSelect-Object -First 1would have taken it. After: the project root's readme, on both hosts.Staging, before and after
Fixture built with
CopyDirectories = @(), a readme, a hand-writtenen-USabout topic, anda
bin/holding no help (binis the culture name for Bini).Messages.psd1en-US/Messages.psd1bin/stagedClosing the blind spot
tests/fixtures/PSBuildTestFixturehad no culture directory, no.psd1below its root andno about topic, so the suite was structurally incapable of seeing any of these three — which
is how all of them survived since 2018. It now ships
en-US/Messages.psd1and a hand-writtenen-US/about_PSBuildTestFixture.help.txt.Assertions that moved because of it, each deliberate:
Build-PSBuildModule.tests.ps1— "Produces only the manifest and a monolithic root module"keeps its count of 2. That count is now the Staging flattens a culture directory's .psd1 into the output root #211 guard: the flattened
Messages.psd1madeit 3.
fixture's about topic first, so they still cover conversion rather than Compile and non-compile modes disagree on whether the readme or a source about file wins #212's precedence.
Build-PSBuildModule silently writes no about help file when the culture directory already exists #207's guard was on the culture directory; Compile and non-compile modes disagree on whether the readme or a source about file wins #212's is on the about file, so the empty
destination directory Build-PSBuildModule silently writes no about help file when the culture directory already exists #207 is about still behaves as it did.
Build-PSBuildHelp.tests.ps1— the cabinet context asserted "no warnings at all". PlatyPS1.x warns
File '' is not a valid help file typefor any file in the module's localedirectory that is not the generated MAML — an about topic included, with an empty name in
its own message. Upstream behavior about module content, so the assertion narrowed to "no
landing-page warning", which is the defect it pins.
Test plan
./build.ps1 -Task Testgreen: 608 passed, 0 failed, 3 skipped (591 before).CopyDirectories, no flattenedroot
.psd1,bin/not staged, readme conversion in both modes, and source-about-topicprecedence with the warning in both modes.
consumer sees on upgrade.