diff --git a/README.md b/README.md index d466438..f752c63 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,23 @@ wsl2-devkit provisions a fresh machine in four staged scripts: baseline Windows apps, WSL2 + Ubuntu, the full Linux dev toolchain, and VS Code — then hands you a one-command **health check** to prove it all worked. -**Design principle:** Windows stays clean. Editors, browsers and fonts live on Windows; every language runtime, linter and CLI tool lives in WSL2, where your code runs fast. +**Design principle:** Windows stays clean. Editors, browsers and fonts live on Windows; every language runtime, linter and CLI tool lives in WSL2, where your code runs fast. Think of it as **workstation-as-code** — the rigor fleet tooling applies to server farms, applied to one machine. The kit enforces the separation by design, not by hope. + +
+New to WSL2? What it is and why isolation matters + +Developing on Windows used to mean choosing between two compromises: install every runtime directly on Windows and watch it slow down under the clutter, or run Linux in a virtual machine and fight the sluggish filesystem and clunky window. + +**WSL2** (Windows Subsystem for Linux) removed that trade-off — Windows runs a real Linux system *inside* itself, at native speed, no dual-boot, no second computer. It's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. + +Isolation is what makes it liberating: + +- **Experiment freely** — languages, tools, and config live inside the Linux environment, which you can rebuild from scratch in minutes whenever you choose. Windows never notices. +- **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. +- **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. +- **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. + +
--- @@ -239,12 +255,30 @@ doesn't do: `~/.bashrc` block is replaced (not duplicated) between markers, and a flaky network on any single download degrades to a warning instead of aborting the run. +Don't take any of this on faith — each claim maps to something checkable: + +| Claim | Where to check | +|---|---| +| ~30 minutes, fresh PC → verified dev machine | Stage timings in the quick start above | +| 52-check health verifier | [wsl/verify-setup.sh](wsl/verify-setup.sh), run on every CI push | +| 8/8 vendor installers pinned + checksum-verified in-repo | `fetch_verified()` in [wsl/stage2-ubuntu.sh](wsl/stage2-ubuntu.sh) | +| Idempotency is CI-enforced, not claimed | Twice-run byte-identical assert in [ci.yml](.github/workflows/ci.yml) | +| Every release ships script checksums | `checksums.txt` on each [release](https://github.com/elirancv/wsl2-devkit/releases) | + ## Requirements - Windows 10 version 2004 (build 19041) or later, or Windows 11 - Virtualization enabled in firmware (for WSL2) - Administrator access for Stage 1 +## FAQ + +**How is this different from dotfiles?** Dotfiles personalize an environment that already works — prompts, aliases, editor settings. wsl2-devkit builds the environment underneath: OS features, `.wslconfig` sizing, language toolchains, keys, and the host↔WSL editor bridge. Your dotfiles layer on top nicely. + +**I already have WSL2.** Stage 2 alone still gets you the toolchain + shell setup, and `verify-setup.sh` will tell you what's missing. Everything is safe to re-run. + +**Why not Dev Containers / Ansible?** Different job. This is a *personal machine* bootstrap optimized for native speed and a clean host — not fleet configuration management. The scaffolding it installs works fine with containers on top. + ## Documentation Full reference — every setting, the staging rationale, and troubleshooting — lives in [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md). Version history is in [CHANGELOG.md](CHANGELOG.md). diff --git a/docs/PRESS-KIT.md b/docs/PRESS-KIT.md deleted file mode 100644 index 3bf9c3c..0000000 --- a/docs/PRESS-KIT.md +++ /dev/null @@ -1,62 +0,0 @@ -# wsl2-devkit — Press Kit - -Everything you need to write or talk about wsl2-devkit. Quote freely; it's MIT. - -**Links:** [Repository](https://github.com/elirancv/wsl2-devkit) · [Latest release](https://github.com/elirancv/wsl2-devkit/releases/latest) · [Full documentation](DOCUMENTATION.md) - ---- - -## One-liner - -> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — and keep Windows clean while doing it. - -## The pitch — for people who've never heard of WSL2 - -Windows can run a real Linux system *inside* itself — no dual-boot, no slow virtual machine window, no second computer. Microsoft calls it **WSL2** (Windows Subsystem for Linux), and it's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. - -The catch: setting it up *well* — the languages, the tooling, the SSH keys, the terminal that doesn't look like 1995 — takes an evening of googling and a dozen chances to get something wrong. - -**wsl2-devkit is that evening, scripted.** Four steps you run in order. It asks what you want (Node? Python? Go? Rust?), installs it the right way, and finishes with a **52-point health check** that proves everything works. It even comes with an undo button: built-in backup, restore, and reset tools. - -## The pitch — for engineers - -wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/11 + WSL2 Ubuntu: - -- **Four ordered stages** — winget apps → WSL2 + auto-sized `.wslconfig` → dev toolchain (nvm/pnpm/bun, pyenv/uv, pinned Go, rustup, modern CLI: eza · bat · ripgrep · fzf · zoxide · starship · lazygit · gh) → VS Code extensions installed *into the WSL server*, not inertly on Windows. -- **Supply chain you can audit** — every vendor installer script is fetched from an **immutable tag/commit ref and verified against a SHA256 committed in the repo** before a byte executes. The Go tarball is version-pinned + checksummed. Releases ship `checksums.txt`. -- **CI that tests the kit, not just the syntax** — every push runs the real installer **twice** on a clean runner and asserts the managed `~/.bashrc` block is *byte-identical* after the re-run, then passes the 52-check verifier. ShellCheck, PSScriptAnalyzer, and a genuine Windows PowerShell 5.1 parse job gate every PR. -- **Unattended mode** — `--yes` / `--all` / `--profile file.conf` for golden images and repeatable rebuilds. -- **Day-2 tooling** — health verifier, distro backup with rotation, validated restore, VHD compaction, typed-confirmation reset. -- **No telemetry. Keys generated locally. MIT.** - -## Design principle - -**Windows stays clean.** Editors, browsers, and fonts live on Windows; every language runtime, linter, and CLI tool lives in WSL2, where the filesystem is fast. The kit enforces the separation instead of hoping you maintain it. - -## Numbers that are true - -| Claim | Backing | -|---|---| -| ~30 minutes, fresh PC → verified dev machine | Stage timings in the README | -| 52-check health verifier | `wsl/verify-setup.sh`, run on every CI push | -| 8/8 vendor installers pinned + checksum-verified in-repo | `fetch_verified()` in `wsl/stage2-ubuntu.sh` | -| Idempotency is CI-enforced, not claimed | Twice-run byte-identical assert in `.github/workflows/ci.yml` | -| Every release ships script checksums | `checksums.txt` on each release | - -## Assets - -- **Hero GIF** (terminal walkthrough, 1200×750): [`demo/devkit-demo.gif`](../demo/devkit-demo.gif) — reproducible via `make demo`, fully anonymized -- Architecture + flow diagrams: rendered Mermaid in the [README](../README.md#how-it-works) -- Suggested screenshot: the verifier's green `52 passed, 0 warnings, 0 missing` summary - -## FAQ ammunition - -**Is it safe to run scripts like this?** Read them first — that's the intended workflow. They're plain PowerShell/bash, MIT-licensed, no telemetry, and each release publishes SHA256 checksums so you can audit a tag and run exactly those bytes. - -**I already have WSL2.** Stage 2 alone still gets you the toolchain + shell setup, and `verify-setup.sh` will tell you what's missing. Everything is safe to re-run. - -**Why not Dev Containers / Ansible?** Different job. This is a *personal machine* bootstrap optimized for native speed and a clean host — not fleet configuration management. The scaffolding it installs works fine with containers on top. - -## Boilerplate - -> **wsl2-devkit** is an open-source (MIT) provisioning kit that turns a fresh Windows 10/11 machine into a complete, verified Linux development environment using WSL2 — in four staged scripts and about 30 minutes. Built by [Eliran Cohen](https://github.com/elirancv).