ClickHouse / ClickHouse/ClickHouse_Demos

feat(workshop): add persistent macOS and Windows learner tracks

Open
#63 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
9
Forks
3
Avg merge
14h 3m
Merged PRs (30d)
6

Description

## Problem

The workshop currently presents 44 Bash command blocks across seven learner modules, plus POSIX paths, heredocs, `$HOME`, `curl | sh`, and `preflight.sh`. A Windows learner can easily run these in PowerShell and fail before reaching ClickHouse.

Learners need to choose macOS or Windows once, see an explicit shell contract on every page, and complete the same workshop without translating commands themselves.

## Platform decision

- **macOS:** run workshop commands in Terminal using zsh/bash.
- **Windows:** use Windows 10 2004+ or Windows 11, Ubuntu on WSL 2, and Docker Desktop with WSL integration. Run the workshop commands inside Ubuntu, not native PowerShell.
- PowerShell is used only for the host bootstrap commands that install/check WSL.
- Clone the repository inside the WSL Linux filesystem (`~/ClickHouse_Demos`), not `/mnt/c`, to avoid bind-mount performance and line-ending problems.

This follows Microsoft’s WSL model for running Linux Bash tools unmodified and Docker’s recommendation to keep code inside the Linux distribution when developing with the WSL 2 backend.

## Deliverables

- Persistent macOS/Windows selector available on every workshop docs page.
- Automatic first-visit OS suggestion with an explicit user override stored across navigation/reload.
- Per-page shell banner: Terminal on macOS; Ubuntu (WSL 2) on Windows.
- Module 00 platform setup with copyable macOS and Windows host/WSL commands.
- Explicit Docker Desktop WSL engine/integration checks and a Windows localhost verification.
- Windows-specific troubleshooting for wrong shell, repo under `/mnt/c`, CRLF, WSL 1, Docker integration, memory, and browser OAuth.
- Instructor guidance for mixed macOS/Windows rooms.
- Scoped `.gitattributes` rules that keep workshop shell scripts LF on Windows checkouts.
- A `windows-latest` CI job that validates the Windows documentation contract, PowerShell syntax, Windows checkout line endings, Bash scripts, MDX/types, and the production playbook build.

## Success criteria

- Selecting Windows immediately shows the WSL instructions and hides macOS-only setup.
- The choice persists after reload and while moving between learner and instructor tracks.
- Keyboard and screen-reader users can identify and change the selector.
- Every learner page says which terminal to use; no command requires implicit shell translation.
- Windows setup ends with successful `wsl --status`, WSL version 2, `docker version`, `docker compose version`, and repo path checks.
- Module 00 still installs both `clickhousectl` and the `clickhouse` client and runs `./preflight.sh` from the app directory.
- All current macOS instructions remain valid.
- PRs cannot pass if the Windows compatibility job fails.

## Test cases

1. Windows host bootstrap commands parse in PowerShell 7.
2. A Windows checkout preserves LF for every workshop `.sh` file; every script passes `bash -n` under Git Bash.
3. The playbook installs, type-checks, and builds on `windows-latest` with Node 22.12.
4. The platform contract checker fails if the selector, WSL command, WSL Docker integration, Linux-filesystem clone path, or shell guidance is removed.
5. Browser QA: macOS -> Windows -> reload -> navigate Module 00/01/07/08 -> instructor track -> choice remains Windows.
6. Browser QA: switching back to macOS updates every platform banner and persists.
7. Responsive QA at 375, 768, and 1280 px shows a usable selector with no overflow.
8. Existing documentation policy, shell syntax, backend tests, frontend build, and playbook build remain green.

## References

- Microsoft WSL install: https://learn.microsoft.com/windows/wsl/install
- Docker Desktop WSL 2 backend: https://docs.docker.com/desktop/features/wsl/
- Docker WSL development workflow: https://docs.docker.com/desktop/features/wsl/use-wsl/
- ClickHouse supported-platform guidance: https://clickhouse.com/support/platforms

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.