docs: Record the Windows commit-message hang as a known issue - #202
Merged
Conversation
1.0.0 ships #167 unfixed, so consumers should find that in the release notes rather than by waiting on a build that never starts. On Windows a build hangs with no output and no error when the HEAD commit message is large. The cause is a deadlock in BuildHelpers\Invoke-Git, which redirects git's output streams and waits for the process to exit before reading them; Get-BuildVariable calls it to populate $env:BHCommitMessage, so the payload is the whole commit message body. Initialize-PSBuild calls Set-BuildEnvironment, so any consumer building on Windows can reach it. The note carries the workaround and, more usefully, the reason continuous integration will not warn anyone: on a pull_request event the checked-out merge commit has a short message, so the build is green and the real message only becomes HEAD on the push to the default branch. Without that detail a consumer reasonably concludes their pipeline is fine. The fix belongs in BuildHelpers rather than in a workaround here, so that every consumer of Invoke-Git benefits rather than only this module. The diagnosis has been posted to the upstream issue, open since 2018 with the symptom but not the cause, and #167 moved to v1.1.0 because it is gated on the PowerShell org's adoption of BuildHelpers completing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
Review of this pull request caught that the note was only half true. It described the hang as size-dependent, which tells a consumer that keeping commit messages short makes them safe. It does not. Closed PR #168 established a second face of the same defect: Invoke-Git deadlocks inside a PowerShell background job whatever the output size -- an 85-byte commit message and a five-byte rev-parse both hang. So calling Initialize-PSBuild or Set-BuildEnvironment from Start-Job hangs unconditionally, and no message-length discipline helps. A consumer following the note as written would conclude their pipeline was safe. Also adds recovery guidance, which the note lacked entirely: shortening the message releases an already-hung build, and nothing needs cleaning up because the build never started. Caught in review of #202. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
The test-file table in repository-specific.instructions.md was corrected in #188, which found it listing 5 of the 15 files that existed. #187 then added tests/LocalizedData.tests.ps1 without adding a row -- the same omission, one merge later. Folded into this documentation-only pull request rather than opened separately because it is a single row in a table two sibling pull requests are already amending, and leaving it would mean the table is wrong again the moment they land. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
The changelog was the wrong home on three counts, and the review of this pull request said so before I argued past it. Keep a Changelog, which this file declares it follows, defines six change types: Added, Changed, Deprecated, Removed, Fixed, Security. The note was a seventh, sitting in the file's section list alongside the real ones. This repository's own rule says CHANGELOG.md documents user-facing *changes* to the shipped module. A known issue is not a change. And it is not new to this version. It is a BuildHelpers defect that affects 0.8.x identically, so a release-scoped entry has the wrong shape for a bug that spans every release including ones already shipped. The README is version-agnostic and is where someone whose build hangs with no output would look. Nothing is lost: the note keeps the cause, the threshold, the recovery step, the reason continuous integration stays green, and the background-job trigger that message length does not fix. For the record on how it got here: the reviewer flagged the changelog placement, and I suppressed the finding by citing the decision comment on #167 as mandating it. That comment was mine, written an hour earlier, so the justification was circular. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
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.
Adds a known-issue note to the 1.0.0 changelog summary for #167, which 1.0.0 ships unfixed.
Why this belongs in the release notes
Initialize-PSBuildcallsSet-BuildEnvironment, so this is not confined to this repository's own builds — any consumer building on Windows can hit it. The failure mode is a hang with no output and no error, which is close to undiagnosable without knowing the cause.Right now that fact lives only on #167. A consumer upgrading to 1.0.0 has no way to find it.
What the note says
WaitForExit-before-ReadToEnddeadlock inBuildHelpers\Invoke-Git, reached becauseGet-BuildVariablepasses the whole commit message body through it.pull_requestevent the checked-out merge commit has a short message, so the build is green; the real message only becomes HEAD on the push to your default branch. Without that, a consumer reasonably concludes their pipeline is fine and is surprised later.Related work, not in this PR
v1.1.0. The fix is gated on the PowerShell org's adoption of BuildHelpers completing (powershellorg/.github#14, approved 2026-08-19), which has no ETA, so it cannot close before 1.0.0 and should not sit in a milestone implying otherwise.A local workaround was considered and rejected: it would be code written to be deleted, and it would fix the symptom for PowerShellBuild consumers while leaving the deadlock in place for everyone else using
Invoke-Git.Verification
Full suite 503 passed, 0 failed, 3 skipped;
Analyzeclean.CHANGELOG.mdverified CRLF-only, no lone LF, no\r\r\n.Note two agents are concurrently working #98/#201 and #103, both of which may add
CHANGELOG.mdentries. Any conflict will be a trivial keep-both in the same list.🤖 Generated with Claude Code
https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE