Compile and non-compile modes disagree on whether the readme or a source about file wins

从 Build-PSBuildModule 开始，跟踪两种 CompileModule 模式中的 readme 块、批量源代码复制和 CopyDirectories。启用 ConvertReadMeToAboutHelp 并使用手写的特定 culture 的 about 文件，重现冲突，然后查看相关 issue #207、#210 和 #211。当优先级或警告行为经过有意选择，并且在两种模式下保持一致时，即视为完成。

Found while researching #207, and only visible once that issue is fixed.

The disagreement

Both modes can produce <Culture>/about_<Module>.help.txt, from two different sources, and they resolve the conflict differently — by accident of statement ordering rather than by design.

Non-compile mode. The readme block runs, then the bulk stage copies the whole source tree:

Copy-Item -Path (Join-Path $Path "*") -Destination $DestinationPath -Recurse -Force

That runs after, so a hand-written en-US/about_<Module>.help.txt in source overwrites the readme-derived one. Source wins.

Compile mode. There is no bulk copy. Once #207 is fixed the readme copy runs unconditionally, and the source about file only reaches the output if CopyDirectories names the culture directory — in which case CopyDirectories runs before the readme block. The readme wins.

So the same two inputs give opposite results depending on a setting that has nothing to do with help.

How to see it

Set ConvertReadMeToAboutHelp = $true and ship a hand-written en-US/about_<Module>.help.txt, then build twice, changing only CompileModule. In non-compile the hand-written text survives; in compile (post-#207) the readme replaces it.

Measured this way while validating the #207 fix. On main today the compile case produces no about file at all, so the disagreement is masked by the bug rather than absent.

Is either answer right?

Arguable both ways, which is why this is its own issue rather than a line in #207:

• Source should win. A consumer who hand-wrote a conformant about topic has expressed a clear preference, and a Markdown readme is not a conformant about topic — it satisfies none of the TOPIC / four-space-indent structure Get-Help documents. Overwriting the good one with the bad one is the worse outcome.
• The readme should win. ConvertReadMeToAboutHelp = $true is an explicit instruction. Silently ignoring it because a file happens to exist is how #207 happened in the first place.
• The combination is contradictory and deserves a warning rather than a silent winner either way.

What is not defensible is the current state, where the answer depends on CompileModule.

Scope

Narrow today. Of 86 surveyed public consumers, none sets ConvertReadMeToAboutHelp through $PSBPreference; the only users reach it by calling Build-PSBuildModule directly. 14 ship a hand-written about topic. No consumer is known to do both, so nobody is hitting this now.

Worth settling anyway, because #207 makes the compile-mode behavior real for the first time, and it is cheaper to decide the precedence deliberately now than to discover it later as a surprise.

Related

#207 (the readme copy being skipped), #210 (a source about file being dropped entirely in compile mode), #211 (culture-directory files flattened into the output root). All four are the same staging logic; the precedence question here only becomes answerable once the other three are settled.