docs: Record the Windows commit-message hang as a known issue

README.md

@@ -25,7 +25,7 @@
 > example.
 
 <p align="center">
     <img src="media/psaketaskmodule-256x256.png" alt="Logo">
 </p>
 
 ## Status - Work in progress
@@ -90,10 +90,10 @@
 | Setting                                                     | Default value                               | Description                                                                                                                                                                  |
 |-------------------------------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | $PSBPreference.General.ProjectRoot                          | `$env:BHProjectPath`                        | Root directory for the project                                                                                                                                               |
 | $PSBPreference.General.SrcRootDir                           | `$env:BHPSModulePath`                       | Root directory for the module                                                                                                                                                |
 | $PSBPreference.General.ModuleName                           | `$env:BHProjectName`                        | The name of the module. This should match the basename of the PSD1 file                                                                                                      |
 | $PSBPreference.General.ModuleVersion                        | `\<computed>`                               | The version of the module                                                                                                                                                    |
 | $PSBPreference.General.ModuleManifestPath                   | `$env:BHPSModuleManifest`                   | Path to the module manifest (PSD1)                                                                                                                                           |
 | $PSBPreference.Build.OutDir                                 | `$projectRoot/Output`                       | Output directory when building the module                                                                                                                                    |
 | $PSBPreference.Build.ModuleOutDir                           | `$outDir/$moduleName/$moduleVersion`        | `For internal use only. Do not overwrite. Use '$PSBPreference.Build.OutDir' to set output directory`                                                                         |
 | $PSBPreference.Build.CompileModule                          | `$false`                                    | Controls whether to "compile" module into single PSM1 or not                                                                                                                 |
@@ -124,17 +124,17 @@
 | $PSBPreference.Help.ConvertReadMeToAboutHelp                | `$false`                                    | Convert project readme into the module about file                                                                                                                            |
 | $PSBPreference.Docs.RootDir                                 | `$projectRoot/docs`                         | Directory PlatyPS markdown documentation will be saved to. Other content in this directory, such as a README or an images folder, is left alone.                             |
 | $PSBPreference.Docs.Overwrite                               | `$false`                                    | Overwrite the markdown files in the docs folder using the comment based help as the source of truth.                                                                         |
 | $PSBPreference.Docs.ExcludeDontShow                         | `$false`                                    | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.                                                                              |
 | $PSBPreference.Docs.UseFullTypeName                         | `$false`                                    | Indicates that the target document will use a full type name instead of a short name for parameters.                                                                         |
 | $PSBPreference.Publish.PSRepository                         | `PSGallery`                                 | PowerShell repository name to publish                                                                                                                                        |
 | $PSBPreference.Publish.PSRepositoryApiKey                   | `$env:PSGALLERY_API_KEY`                    | API key to authenticate to PowerShell repository with                                                                                                                        |
 | $PSBPreference.Publish.PSRepositoryCredential               | `$null`                                     | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined                                                                         |
 | $PSBPreference.Sign.Enabled                                 | `$false`                                    | Enable/disable Authenticode signing of the built module. Must be `$true` for any of the signing or catalog tasks to run.                                                     |
 | $PSBPreference.Sign.CertificateSource                       | `Auto`                                      | How the code-signing certificate is resolved. Valid values are `Auto`, `Store`, `Thumbprint`, `EnvVar`, and `PfxFile`. See [Code signing](#code-signing).                    |
 | $PSBPreference.Sign.CertStoreLocation                       | `Cert:\CurrentUser\My`                      | Windows certificate store path searched by the `Store` and `Thumbprint` certificate sources.                                                                                 |
 | $PSBPreference.Sign.Thumbprint                              | `$null`                                     | Thumbprint of the certificate to select from the store. Required by the `Thumbprint` certificate source and ignored by the others.                                           |
 | $PSBPreference.Sign.CertificateEnvVar                       | `SIGNCERTIFICATE`                           | Name of the environment variable holding the Base64-encoded PFX. Read by the `EnvVar` source, and used by `Auto` to detect whether a certificate is present.                 |
 | $PSBPreference.Sign.CertificatePasswordEnvVar               | `CERTIFICATEPASSWORD`                       | Name of the environment variable holding the password for the Base64-encoded PFX. Read by the `EnvVar` certificate source.                                                   |
 | $PSBPreference.Sign.PfxFilePath                             | `$null`                                     | File system path to a PFX/P12 certificate file. Required by the `PfxFile` certificate source.                                                                                |
 | $PSBPreference.Sign.PfxFilePassword                         | `$null`                                     | Password for the PFX/P12 file as a `SecureString`. Used by the `PfxFile` certificate source.                                                                                 |
 | $PSBPreference.Sign.Certificate                             | `$null`                                     | A pre-resolved `X509Certificate2` object to sign with. When set, `CertificateSource` is ignored, which suits Azure Key Vault, an HSM, or another custom provider.            |
@@ -270,6 +270,50 @@
 
 ![Example](./media/ib_example.png)
 
+## Known issues
+
+### Windows builds can hang on a large commit message
+
+On Windows a build can hang with **no output and no error** when the HEAD
+commit message is large — roughly 5.7 KB in measurement, though the real
+limit is a pipe-buffer size rather than a fixed number. Linux and macOS
+have a larger buffer and do not reach it at these sizes.
+
+This is not a defect in PowerShellBuild and is not specific to any
+version. It is a deadlock in `BuildHelpers\Invoke-Git`, which redirects
+git's output streams and then waits for the process to exit *before*
+reading them; when git writes more than the pipe holds, neither side can
+proceed. `Get-BuildVariable` calls it to populate `$env:BHCommitMessage`,
+so the payload is the whole commit message body. It reaches you because
+`Initialize-PSBuild` calls `Set-BuildEnvironment`.
+
+**Keep commit messages under a few kilobytes.** If you squash-merge pull
+requests, use a short squash body — the full description stays on the
+pull request either way.
+
+**If a build is already hung**, shortening the message releases it:
+`git commit --amend` locally, or fast-forward a checkout sitting on the
+offending commit. Nothing needs cleaning up, because the build never
+started.
+
+**Continuous integration will not warn you.** On a `pull_request` event
+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.
+
+**Size is not the only trigger.** `Invoke-Git` also deadlocks inside a
+PowerShell background job *whatever* the output size — an 85-byte commit
+message and a five-byte `git rev-parse` both hang. Calling
+`Initialize-PSBuild` or `Set-BuildEnvironment` from `Start-Job` therefore
+hangs unconditionally, and no message-length discipline helps. Run them in
+the foreground, or in a child process you can time out.
+
+Tracked upstream as
+[RamblingCookieMonster/BuildHelpers#86](https://github.com/RamblingCookieMonster/BuildHelpers/issues/86)
+and here as
+[#167](https://github.com/psake/PowerShellBuild/issues/167). The fix
+belongs in BuildHelpers rather than in a workaround here, so that every
+consumer of `Invoke-Git` gets it rather than only this module.
+
 [github-actions-badge]: https://github.com/psake/PowerShellBuild/actions/workflows/test.yml/badge.svg
 [github-actions-badge-publish]: https://github.com/psake/PowerShellBuild/actions/workflows/publish.yaml/badge.svg?event=release
 [github-actions-build]: https://github.com/psake/PowerShellBuild/actions

instructions/repository-specific.instructions.md

@@ -263,6 +263,7 @@
 | `IBTasks.tests.ps1`                      | Invoke-Build task definitions and the settings they reference        |
 | `Initialize-PSBuild.tests.ps1`           | Build environment initialization                                     |
 | `Invoke-PSBuildModuleSigning.tests.ps1`  | Authenticode signing of module files                                 |
+| `LocalizedData.tests.ps1`                | How the module resolves its user-facing strings at import            |
 | `Manifest.tests.ps1`                     | Module manifest validity                                             |
 | `Meta.tests.ps1`                         | Text file formatting across the repository                           |
 | `New-PSBuildFileCatalog.tests.ps1`       | Catalog (`.cat`) file creation                                       |
@@ -289,7 +290,7 @@
 
 - Triggers: manual dispatch, GitHub release published
 - Runs on: `ubuntu-latest`
 - Reads `PSGALLERY_API_KEY` secret, converts to `PSCredential`, runs
   `./build.ps1 -Task Publish -PSGalleryApiKey $cred -Bootstrap`
 
 ## Repo-Specific Conventions
@@ -370,8 +371,8 @@
 | ------------------------- | ---------------------------------------------------- |
 | `$env:BHProjectPath`      | Repository root directory                            |
 | `$env:BHProjectName`      | Module name (from directory structure)               |
 | `$env:BHPSModulePath`     | Path to module source directory                      |
 | `$env:BHPSModuleManifest` | Path to `.psd1` manifest                             |
 | `$env:BHModulePath`       | Same as `BHPSModulePath`                             |
 | `$env:BHBuildSystem`      | Detected CI system (e.g., `GitHubActions`, `Unknown`)|
 | `$env:BHBranchName`       | Current git branch                                   |