Compiling drops a hand-written about_<Module>.help.txt unless CopyDirectories names the culture directory

从 Build-PSBuildModule 的 compile-mode 暂存逻辑入手，并将其与非编译复制路径进行比较。在决定应如何处理 Culture 目录或 about topics 之前，先查看相关 issue #206 和 #207。完成的标准是实现约定的行为，使手写的 about topic 不再静默地缺失于编译后的包中。

Found while surveying how consumers configure PowerShellBuild, for the decisions on #206 and #207. Verified in packages already published to the PowerShell Gallery, so this is affecting real modules today rather than being a hypothetical.

What happens

In compile mode, Build-PSBuildModule stages only three things into the output:

1. *.psm1, *.psd1 and *.ps1xml at depth 1
2. whatever $PSBPreference.Build.CopyDirectories names
3. the concatenated *.ps1 files from CompileDirectories, written into the root module

A hand-written en-US/about_<Module>.help.txt in the source tree is none of those. It is silently left behind, and the built module ships without its about topic. The build reports success.

Non-compile mode is unaffected: it does a bulk Copy-Item $Path/* -Recurse -Force, so the whole source tree including en-US/ arrives in the output.

Evidence from published packages

Downloaded the .nupkg for five consumers that ship a hand-written about topic in source:

All five have about_*.help.txt in their source tree. The only thing separating the two groups is whether CopyDirectories happens to name the culture directory.

For the three affected modules the published en-US/ contains only the platyPS-generated MAML (<Module>-help.xml). Get-Help about_<Module> returns nothing for their users.

Why it is easy to miss

Nothing warns. The consumer sees a green build and a package that looks complete, and the file they wrote is simply absent. It is the same shape as #201 and #207 — a plausible-looking artifact with something quietly missing — and the three affected authors presumably do not know.

It is also not obvious from the settings. CopyDirectories reads as an escape hatch for extra content, not as the mechanism by which help files reach the output; a consumer who ships an about topic has no particular reason to think it applies to them.

Scope

14 of the 86 surveyed public consumers ship a hand-written about topic. Four of those compile. Three of the four are affected; the fourth (Plaster) is safe only because it sets CopyDirectories for unrelated reasons.

Options

1. Stage <Culture>/ automatically in compile mode, the way *.psd1 and *.psm1 are staged, since a culture directory is part of a module rather than incidental content. Closest to what a consumer expects, and makes CopyDirectories = @("en-US") unnecessary rather than load-bearing.
2. Stage any about_*.help.txt found under a culture directory, narrower than (1) — it would not bring Messages.psd1 or other localized data along, which some modules do want and others may not.
3. Warn when compiling if a culture directory exists in source and CopyDirectories does not name it. No behavior change; makes the silent drop visible. Weakest, but the least likely to surprise anyone.
4. Document it in the CopyDirectories settings row and the README. Cheapest; leaves three published modules broken and the next consumer to hit it none the wiser.

I lean (1). A module's culture directory carries its localized data and its about topics, and dropping it while carefully copying the manifest is hard to justify as intended behavior. But it changes what lands in the output for every compiling consumer, so it is a maintainer call.

Related: #206 and #207 are also in Build-PSBuildModule's staging logic, and #207 in particular concerns the same culture directory. Worth deciding the three together.