Skip to content

feat(scripts): add Windows shell pre-flight check and WSL2 documentation - #263

Merged
Calvin-Cheng1 merged 5 commits into
mainfrom
feat/252-windows-preflight-and-devcontainer
Sep 25, 2026
Merged

Calvin-Cheng1 merged 5 commits into
mainfrom
feat/252-windows-preflight-and-devcontainer

Conversation

@aghassemlouei

@aghassemlouei aghassemlouei commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Description

Adds a pre-flight shell check for unsupported native Windows shell environments and documents the WSL2 requirement and native Windows limitations.

In native Windows terminals (MINGW64, MSYS, CYGWIN, or Windows shells outside WSL2), POSIX path handling, CRLF line endings, and symlink generation (ln -s) in fast/stage-links.sh and scripts/*.sh can fail midway through execution. This change:

  • Adds check_os_environment to scripts/common-functions.sh (invoked automatically by check_prerequisites) so scripts fail fast with guidance to use WSL2 or Google Cloud Shell when run from a native Windows shell, while passing normally on Linux, macOS, Cloud Shell, and WSL2.
  • Updates README.md, docs/prerequisites.md, and scripts/README.md to document the WSL2 workstation requirement and explain the path, symlink, and line-ending limitations encountered in native Windows terminals.
  • Adds unit tests in tests/scripts/test_common_functions.sh covering Linux, macOS, WSL2, MINGW64, Cygwin, and native Windows_NT.

Fixes #252

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

  • Executed bash tests/scripts/run_shell_tests.sh verifying all 27 shell scripts pass syntax validation and all 19 unit assertions in tests/scripts/test_common_functions.sh pass.

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

@aghassemlouei aghassemlouei added Enhancement New feature or request Level of Effort - Medium Moderate task requiring thought and testing; typically takes a couple of days to a week Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Scope - Fast Related to Fabric FAST deployment stages in the fast directory labels Sep 25, 2026
@Calvin-Cheng1

Copy link
Copy Markdown
Collaborator

How does creating this dockerfile solve the issue? Are we expecting Windows users to:

  1. Have Docker installed
  2. Know how to use the dockerfile to execute the commands?

I think the simplest response is to ditch the .devcontainer and recommend the user run the scripts inside a WSL environment

@aghassemlouei aghassemlouei changed the title feat(scripts): add Windows pre-flight shell check and DevContainer config feat(scripts): add Windows shell pre-flight check and WSL2 documentation Sep 25, 2026
@aghassemlouei aghassemlouei added Documentation Improvements or additions to documentation Level of Effort - Low Quick, well-defined tasks with no unknowns; takes a few hours up to one day to complete and removed Level of Effort - Medium Moderate task requiring thought and testing; typically takes a couple of days to a week labels Sep 25, 2026
@aghassemlouei

aghassemlouei commented Sep 25, 2026 •

Copy link
Copy Markdown
Member Author

Good call; Docker on Windows relies on WSL2 under the hood anyway, and expecting operators on client Windows machines to have Docker set up adds unnecessary friction. I removed .devcontainer and updated README.md, docs/prerequisites.md, and scripts/README.md to document the WSL2 requirement and the path/symlink limitations on native Windows shells.

@Calvin-Cheng1 Calvin-Cheng1 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

lgtm

@Calvin-Cheng1
Calvin-Cheng1 merged commit 5cd0bf2 into main Sep 25, 2026
20 checks passed
@Calvin-Cheng1
Calvin-Cheng1 deleted the feat/252-windows-preflight-and-devcontainer branch September 25, 2026 19:17
@github-actions github-actions Bot mentioned this pull request Sep 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Improvements or additions to documentation Enhancement New feature or request Level of Effort - Low Quick, well-defined tasks with no unknowns; takes a few hours up to one day to complete Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Scope - Fast Related to Fabric FAST deployment stages in the fast directory

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Add pre-flight OS/shell environment checks and containerized workstation support for Windows

4 participants