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

[tablackburn]

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 Build-PSBuildModule silently writes no about help file when the culture directory already exists #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.