Skip to content

fix(docs): serialize Windows Astro output - #11357

Merged
ReubenBond merged 2 commits into
dotnet:mainfrom
ReubenBond:rb-fix-docs-output-race
Sep 30, 2026
Merged

ReubenBond merged 2 commits into
dotnet:mainfrom
ReubenBond:rb-fix-docs-output-race

Conversation

@ReubenBond

@ReubenBond ReubenBond commented Sep 30, 2026 •

Copy link
Copy Markdown
Member

Problem

Astro prerenders documentation routes concurrently. On Windows, concurrent routes can share output directories and intermittently fail between directory creation and file publication with ENOENT. Node 24.19 can then terminate with a secondary libuv shutdown assertion while handling the build failure.

The race became observable after the Astro documentation site was introduced and the Markdown companion integration expanded the prerender route set.

The first PR run also confirmed that Twitter serves the public Orleans follow intent to browsers but rejects the documentation link audit's bounded automated probe with HTTP 403.

Solution

  • default Astro route generation to one writer on Windows and retain four workers on other platforms
  • preserve an explicit ORLEANS_DOCS_BUILD_CONCURRENCY override and reject invalid values
  • let Linux documentation CI exercise the platform default instead of duplicating it in workflow configuration
  • document the Windows behavior and the Node 24.20 requirement when opting back into concurrent generation
  • add the exact Twitter follow intent to the reasoned external-link allowlist

Rationale

Serializing only the affected platform establishes a single-writer filesystem invariant without slowing Linux CI. The override remains available for controlled validation as Astro and Node evolve. The exact allowlist entry preserves the useful browser link while keeping all other external targets actively probed.

Closes #10672

Microsoft Reviewers: Open in CodeFlow

Copilot AI balanced review requested due to automatic review settings September 30, 2026 08:36

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The change targets an intermittent Windows build failure, but the available validation does not establish that the full build succeeds on Windows.

Review effort: Balanced
Findings: None

What changed in this PR

This PR aims to prevent intermittent Windows documentation-build failures by serializing Astro route generation there while retaining concurrent generation elsewhere.

Changes:

  • Adds platform defaults, an override, and tests for build concurrency.
  • Removes the redundant Linux CI override and documents the Windows behavior.
File Description
docs/​site/​tests/​build-settings.test.mjs Tests defaults, overrides, and invalid values.
docs/​site/​scripts/​lib/​build-settings.mjs Selects and validates build concurrency.
docs/​site/​README.md Documents platform behavior and Node guidance.
docs/​site/​astro.config.mjs Uses the new concurrency setting.
.github/​workflows/​docs.yml Lets Linux CI use the platform default.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Code coverage

Metric Pull request
Lines 82.92% (115,492 / 139,282)
Branches 72.23% (33,519 / 46,405)

Report-only conclusion: current-main baseline stale.

The newest successful coverage run tested 6bf11ad, not current main 5bebd17.

Coverage combines every CI test matrix job, including providers, CodeGen, .NET 8/10, Linux, Windows, and macOS, using canonical physical source and branch identities.

The comparison remains report-only while normal line and branch variance is calibrated.

Coverage details

Copilot AI balanced review requested due to automatic review settings September 30, 2026 16:53

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The PR description would incorrectly close the unrelated Consul CI issue #11360 on merge.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Low severity Remove incorrect Fixes #11360 closing keyword

docs/​site/​astro.config.mjs:15

The PR description says Fixes #11360, but #11360 is about Consul CI failing to pull an ECR image. This Astro change does not fix that issue, and the closing keyword would close it on merge. Please remove Fixes #11360 from the PR description; keep Closes #10672 for the docs build race.

@ReubenBond
ReubenBond merged commit 825aae7 into dotnet:main Sep 30, 2026
129 of 131 checks passed
@ReubenBond
ReubenBond deleted the rb-fix-docs-output-race branch September 30, 2026 22:15
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 31, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs site Astro build can race on generated output on Windows

2 participants