docs: overhaul Copilot instructions with coding conventions and prompt files (#40113)
* docs: overhaul Copilot instructions with coding conventions and prompt files Major update to .github/copilot-instructions.md: - Add coding conventions (naming, error handling, RAII, strings, headers, synchronization, localization, telemetry, formatting, IDL/COM, config) - Add test authoring summary pointing to detailed test.md prompt - Add namespace-to-directory map for top-level namespaces - Add key source files list (defs.h, WslTelemetry.h, wslc.idl, etc.) - Replace clang-format references with .\FormatSource.ps1 - Consolidate duplicate timing info into single reference table New files: - .github/copilot/review.md: Review prompt focused on high-risk areas (ABI breaks, missing localization, resource safety) - .github/copilot/test.md: Test generation prompt with TAEF patterns - .github/copilot/commit.md: Commit message guidelines - .editorconfig: Editor settings for non-C++ files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: address PR review feedback - Scope precomp.h guidance to Windows components (Linux doesn't use it) - Fix review.md reference to .github/copilot-instructions.md - Restore clang-format as Linux formatting option alongside FormatSource.ps1 - Note FormatSource.ps1 requires cmake . first - Fix en-us -> en-US casing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Ben Hillis <benhill@ntdev.microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ben Hillis committed
Apr 6, 2026 at 15:15 UTC
11ae8b2322cfcb67109b74d79a77dbc8a6fdde77
5 files changed
+422
-101
.editorconfig
new
+43
@@ -0,0 +1,43 @@
1
+# EditorConfig — https://editorconfig.org
2
+# Complements .clang-format for non-C++ files
3
+
4
+root = true
5
+
6
+[*]
7
+indent_style = space
8
+indent_size = 4
9
+end_of_line = crlf
10
+charset = utf-8
11
+trim_trailing_whitespace = true
12
+insert_final_newline = true
13
+
14
+[*.{cpp,h,hpp,c,idl}]
15
+# C/C++ formatting is handled by .clang-format
16
+indent_size = 4
17
+
18
+[*.{yml,yaml}]
19
+indent_size = 2
20
+
21
+[*.{json,jsonc}]
22
+indent_size = 2
23
+
24
+[*.{md,markdown}]
25
+trim_trailing_whitespace = false
26
+
27
+[*.py]
28
+indent_size = 4
29
+
30
+[*.{ps1,psm1,psd1}]
31
+indent_size = 4
32
+
33
+[*.{xml,resw,resx,props,targets,nuspec}]
34
+indent_size = 2
35
+
36
+[*.cmake]
37
+indent_size = 4
38
+
39
+[CMakeLists.txt]
40
+indent_size = 4
41
+
42
+[Makefile]
43
+indent_style = tab
.github/copilot-instructions.md
+252
-101
@@ -4,17 +4,198 @@
4
5
WSL is the Windows Subsystem for Linux - a compatibility layer for running Linux binary executables natively on Windows. This repository contains the core Windows components that enable WSL functionality.
6
7
-## Working Effectively
7
+## Coding Conventions
8
+
9
+### Naming
10
+
11
+- **Classes/Structs**: `PascalCase` (e.g., `ConsoleProgressBar`, `DeviceHostProxy`)
12
+- **Functions/Methods**: `PascalCase()` (e.g., `GetFamilyName()`, `MultiByteToWide()`)
13
+- **Member variables**: `m_camelCase` (e.g., `m_isOutputConsole`, `m_outputHandle`)
14
+- **Local variables**: `camelCase` (e.g., `distroGuidString`, `asyncResponse`)
15
+- **Constants**: `c_camelCase` with `constexpr` (e.g., `constexpr size_t c_progressBarWidth = 58;`)
16
+- **Namespaces**: lowercase with `::` nesting (e.g., `wsl::windows::common::registry`)
17
+- **Enums**: `PascalCaseValue` (e.g., `LxssDistributionStateInstalled`)
18
+- **Windows types**: Keep as-is (`LPCWSTR`, `HRESULT`, `DWORD`, `ULONG`, `GUID`)
19
+
20
+### Error Handling
21
+
22
+Use WIL (Windows Implementation Libraries) macros — **never** bare `if (FAILED(hr))`:
23
+- `THROW_IF_FAILED(hr)` — throw on HRESULT failure
24
+- `THROW_HR_IF(hr, condition)` — conditional throw
25
+- `THROW_HR_IF_MSG(hr, condition, fmt, ...)` — conditional throw with message
26
+- `THROW_IF_NULL_ALLOC(ptr)` — throw on null allocation
27
+- `THROW_LAST_ERROR_IF(condition)` — throw last Win32 error
28
+- `RETURN_IF_FAILED(hr)` — return HRESULT on failure (no throw)
29
+- `RETURN_LAST_ERROR_IF_EXPECTED(condition)` — expected failure path
30
+- `LOG_IF_FAILED(hr)` — log but don't throw
31
+- `CATCH_LOG()` — catch and log exceptions
32
+
33
+For user-facing errors, set a localized message before throwing:
34
+```cpp
35
+THROW_HR_WITH_USER_ERROR(E_INVALIDARG, Localization::MessageConfigInvalidBoolean(name, value));
36
+```
37
+
38
+At API boundaries (COM interfaces), return `HRESULT` with out params. Internal code throws exceptions.
39
+
40
+### Memory Management and RAII
41
+
42
+Use WIL smart pointers — **never** raw `CloseHandle()` or manual cleanup:
43
+- `wil::unique_handle` — kernel handles
44
+- `wil::com_ptr<T>` — COM objects
45
+- `wil::unique_hfile` — file handles
46
+- `wil::unique_hkey` — registry keys
47
+- `wil::unique_event` — events
48
+- `wil::unique_hlocal_string` — HLOCAL strings
49
+- `wil::unique_cotaskmem_string` — CoTaskMem strings
50
+
51
+For non-standard resource types, use `wil::unique_any<Type, Deleter, Fn>`.
52
+
53
+For cleanup scopes, use `wil::scope_exit`:
54
+```cpp
55
+auto cleanup = wil::scope_exit([&] { registry::DeleteKey(LxssKey, guid.c_str()); });
56
+// ... work ...
57
+cleanup.release(); // dismiss on success
58
+```
59
+
60
+### Synchronization
61
+
62
+Use `wil::srwlock` (Slim Reader/Writer locks) with SAL annotations:
63
+```cpp
64
+mutable wil::srwlock m_lock;
65
+_Guarded_by_(m_lock) std::vector<Entry> m_entries;
66
+```
67
+
68
+### Strings
69
+
70
+- `std::wstring` / `std::wstring_view` are dominant throughout the codebase
71
+- Use `MultiByteToWide()` / `WideToMultiByte()` from `stringshared.h` for conversions
72
+- Use `std::format()` for formatting (the repo defines `std::formatter<std::wstring, char>` for wide-to-narrow support)
73
+- The `STRING_TO_WIDE_STRING()` macro handles compile-time conversion
74
+
75
+### Copy/Move Semantics
76
+
77
+Use macros from `defs.h` to declare copy/move behavior:
78
+```cpp
79
+NON_COPYABLE(MyClass);
80
+NON_MOVABLE(MyClass);
81
+DEFAULT_MOVABLE(MyClass);
82
+```
83
+
84
+### Headers
85
+
86
+- Use `#pragma once` (no traditional `#ifndef` include guards)
87
+- In Windows C++ components, every `.cpp` file must start with `#include "precomp.h"`
88
+- Linux-side code (`src/linux/`) does not use precompiled headers
89
+- Use `.h` for C-compatible headers, `.hpp` for C++-only headers
90
+- Include order is enforced by `.clang-format` (precomp first, then system, then project)
91
+
92
+### Copyright Headers
93
+
94
+Use this single-line format for new files:
95
+```cpp
96
+// Copyright (C) Microsoft Corporation. All rights reserved.
97
+```
98
+
99
+Some older files use the block format (`/*++ Copyright (c) Microsoft. All rights reserved. ... --*/`). Match the surrounding files in the same directory when editing.
100
+
101
+### Localization
102
+
103
+- Use `wsl::shared::Localization::MessageXxx()` static methods for user-facing strings
104
+- Use `EMIT_USER_WARNING(Localization::MessageXxx(...))` for non-fatal config warnings
105
+- All new user-facing strings must have entries in `localization/strings/en-US/Resources.resw`
106
+- In Resources.resw comments, use `{Locked="..."}` to prevent translation of `.wslconfig` property key names
107
+
108
+### Telemetry and Logging
109
+
110
+- `WSL_LOG(Name, ...)` — standard trace event
111
+- `WSL_LOG_DEBUG(Name, ...)` — debug-only (compiled out in release via `if constexpr`)
112
+- `WSL_LOG_TELEMETRY(Name, Tag, ...)` — metrics with privacy tag and version info
113
+- Provider: `g_hTraceLoggingProvider`, initialized via `WslTraceLoggingInitialize()`
114
+
115
+### Platform Conditionals
116
+
117
+Prefer `constexpr` checks over `#ifdef` where possible:
118
+```cpp
119
+if constexpr (wsl::shared::Debug) { /* debug-only code */ }
120
+if constexpr (wsl::shared::Arm64) { /* ARM64-specific code */ }
121
+```
122
+
123
+For compiler-specific code, use `#ifdef _MSC_VER` (Windows) / `#ifdef __GNUC__` (Linux).
124
+
125
+### Formatting
126
+
127
+Enforced by `.clang-format`:
128
+- 130 character column limit
129
+- 4-space indentation, no tabs
130
+- Allman-style braces (opening brace on new line for classes, functions, structs, control statements)
131
+- Left-aligned pointers (`int* ptr`, not `int *ptr`)
132
+- `InsertBraces: true` — all control statements must have braces
133
+
134
+### IDL / COM Conventions
135
+
136
+When modifying service interfaces (`src/windows/service/inc/`):
137
+- Interface attributes on separate lines: `[uuid(...), pointer_default(unique), object]`
138
+- String params: `[in, unique] LPCWSTR` with `[string]` for marshaled strings
139
+- Handle params: `[in, system_handle(sh_file)] HANDLE`
140
+- User-facing errors: pass `[in, out] LXSS_ERROR_INFO* Error`
141
+- **Adding methods to an existing interface is an ABI break** — create a new versioned interface with a new IID
142
+- Custom error codes: `WSL_E_xxx` via `MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSL_E_BASE + N)`
143
+
144
+### Config File (.wslconfig) Conventions
145
+
146
+When adding settings to `src/shared/configfile/`:
147
+- Format is `.gitconfig`-style INI: `[section]`, `key = value`, `#` comments, `\` line continuation
148
+- Use the `ConfigKey` template class for type-safe parsing
149
+- Supported types: `bool`, `int` (hex/octal), `std::string`, `std::wstring`, `MemoryString`, `MacAddress`, enum maps
150
+- Report invalid values with `EMIT_USER_WARNING(Localization::MessageConfigXxx(...))`
151
+- New settings require a corresponding localization string in Resources.resw
152
+
153
+## Repository Navigation
154
+
155
+### Key Directories
156
+- `src/windows/` — Main Windows WSL service components
157
+- `src/linux/` — Linux-side WSL components
158
+- `src/shared/` — Shared code between Windows and Linux
159
+- `test/windows/` — Windows-based tests (TAEF framework)
160
+- `test/linux/unit_tests/` — Linux unit test suite
161
+- `doc/` — Documentation source (MkDocs)
162
+- `tools/` — Build and deployment scripts
163
+- `distributions/` — Distribution validation and metadata
164
+- `localization/` — Localized string resources
165
+
166
+### Namespace → Directory Map
167
+
168
+| Namespace | Location |
169
+|---|---|
170
+| `wsl::shared::` | `src/shared/` |
171
+| `wsl::windows::common::` | `src/windows/common/` |
172
+| `wsl::windows::service::` | `src/windows/service/exe/` |
173
+| `wsl::core::` | `src/windows/service/exe/` |
174
+| `wsl::core::networking::` | `src/windows/common/` + `src/windows/service/exe/` |
175
+| `wsl::linux::` | `src/linux/init/` |
176
+
177
+### Key Files
178
+- `src/shared/inc/defs.h` — Shared platform definitions (NON_COPYABLE, Debug, Arm64, etc.)
179
+- `src/shared/inc/stringshared.h` — String conversion utilities
180
+- `src/windows/common/WslTelemetry.h` — Telemetry macros
181
+- `src/windows/common/ExecutionContext.h` — Error context and user-facing error macros
182
+- `src/windows/service/inc/wslservice.idl` — Main service COM interface definitions
183
+- `src/windows/service/inc/wslc.idl` — Container COM interface definitions
184
+- `src/windows/inc/WslPluginApi.h` — Plugin API header
185
+- `src/shared/configfile/configfile.h` — Config file parser
186
+- `.clang-format` — Code formatting rules (130 col, 4-space indent, Allman braces)
187
+
188
+## Building and Deploying
189
190
### Critical Platform Requirements
191
- **Full builds ONLY work on Windows** with Visual Studio and Windows SDK 26100
11
-- **DO NOT attempt to build the main WSL components on Linux** - they require Windows-specific APIs, MSBuild, and Visual Studio toolchain
192
+- **DO NOT attempt to build the main WSL components on Linux** — they require Windows-specific APIs, MSBuild, and Visual Studio toolchain
193
- Many validation and development tasks CAN be performed on Linux (documentation, formatting, Python validation scripts)
194
14
-### Windows Build Requirements (Required for Full Development)
195
+### Windows Build Requirements
196
- CMake >= 3.25 (`winget install Kitware.CMake`)
197
- Visual Studio with these components:
17
- - Windows SDK 26100
198
+ - Windows SDK 26100
199
- MSBuild
200
- Universal Windows platform support for v143 build tools (X64 and ARM64)
201
- MSVC v143 - VS 2022 C++ ARM64 build tools (Latest + Spectre) (X64 and ARM64)
@@ -29,67 +210,49 @@ WSL is the Windows Subsystem for Linux - a compatibility layer for running Linux
210
1. Clone the repository
211
2. Generate Visual Studio solution: `cmake .`
212
3. Build: `cmake --build . -- -m` OR open `wsl.sln` in Visual Studio
32
-4. **NEVER CANCEL: Build takes 20-45 minutes on typical hardware. Set timeout to 60+ minutes.**
213
214
Build parameters:
35
-- `cmake . -A arm64` - Build for ARM64
36
-- `cmake . -DCMAKE_BUILD_TYPE=Release` - Release build
37
-- `cmake . -DBUILD_BUNDLE=TRUE` - Build bundle msix package (requires ARM64 built first)
215
+- `cmake . -A arm64` — Build for ARM64
216
+- `cmake . -DCMAKE_BUILD_TYPE=Release` — Release build
217
+- `cmake . -DBUILD_BUNDLE=TRUE` — Build bundle MSIX package (requires ARM64 built first)
218
39
-### Deploying WSL (Windows Only)
219
+### Deploying WSL (Windows Only)
220
- Install MSI: `bin\<platform>\<target>\wsl.msi`
221
- OR use script: `powershell tools\deploy\deploy-to-host.ps1`
222
- For Hyper-V VM: `powershell tools\deploy\deploy-to-vm.ps1 -VmName <vm> -Username <user> -Password <pass>`
223
44
-## Cross-Platform Development Tasks
45
-
46
-### Documentation (Works on Linux/Windows)
47
-- Install tools: `pip install mkdocs-mermaid2-plugin mkdocs --break-system-packages`
48
-- Build docs: `mkdocs build -f doc/mkdocs.yml`
49
-- **Build time: ~0.5 seconds. Set timeout to 5+ minutes for safety.**
50
-- Output location: `doc/site/`
51
-- **Note**: May show warnings about mermaid CDN access on restricted networks
224
+## Testing
225
53
-### Code Formatting and Validation (Works on Linux/Windows)
54
-- Format check: `clang-format --dry-run --style=file <files>`
55
-- Apply formatting: `clang-format -i --style=file <files>`
56
-- Format all source: `powershell formatsource.ps1` (available at repo root after running `cmake .`)
57
-- Validate copyright headers: `python3 tools/devops/validate-copyright-headers.py`
58
- - **Note**: Will report missing headers in generated/dependency files (_deps/), which is expected
59
-- Validate localization: `python3 tools/devops/validate-localization.py`
60
- - **Note**: Only works after Windows build (requires localization/strings/en-us/Resources.resw)
226
+### Writing Tests (TAEF Framework)
227
62
-### Distribution Validation (Limited on Linux)
63
-- Validate distribution info: `python3 distributions/validate.py distributions/DistributionInfo.json`
64
-- **Note**: May fail on Linux due to network restrictions accessing distribution URLs
228
+Tests use TAEF. See `.github/copilot/test.md` for detailed patterns and macros.
229
66
-## Testing
230
+Key points:
231
+- Use `WSL_TEST_CLASS(Name)` — not raw `BEGIN_TEST_CLASS`
232
+- Use `VERIFY_*` macros for assertions (`VERIFY_ARE_EQUAL`, `VERIFY_IS_TRUE`, etc.)
233
+- Skip macros: `WSL1_TEST_ONLY()`, `WSL2_TEST_ONLY()`, `SKIP_TEST_ARM64()`
234
+- Test infrastructure is in `test/windows/Common.h`
235
68
-### Unit Tests (Windows Only - TAEF Framework)
236
+### Running Tests (Windows Only)
237
238
**CRITICAL: ALWAYS build the ENTIRE project before running tests:**
239
```powershell
72
-# Build everything first - this is required!
240
cmake --build . -- -m
74
-
75
-# Then run tests
241
bin\<platform>\<target>\test.bat
242
```
243
244
**Why full build is required:**
245
- Tests depend on multiple components (libwsl.dll, wsltests.dll, wslservice.exe, etc.)
81
-- Partial builds (e.g., only `configfile` or `wsltests`) will cause test failures
82
-- Changed components must be built together to ensure compatibility
246
+- Partial builds will cause test failures
247
- **DO NOT skip the full build step even if only one file changed**
248
249
Test execution:
250
- Run all tests: `bin\<platform>\<target>\test.bat`
87
-- **NEVER CANCEL: Full test suite takes 30-60 minutes. Set timeout to 90+ minutes.**
251
- Run subset: `bin\<platform>\<target>\test.bat /name:*UnitTest*`
252
- Run specific test: `bin\<platform>\<target>\test.bat /name:<class>::<test>`
253
- WSL1 tests: Add `-Version 1` flag
254
- Fast mode (after first run): Add `-f` flag (requires `wsl --set-default test_distro`)
92
-- **Requires Administrator privileges** - test.bat will fail without admin rights
255
+- **Requires Administrator privileges**
256
257
Test debugging:
258
- Wait for debugger: `/waitfordebugger`
@@ -101,62 +264,58 @@ Test debugging:
264
- Build script: `test/linux/unit_tests/build_tests.sh`
265
- **Note**: Requires specific Linux build environment setup not covered in main build process
266
104
-## Validation Scenarios
267
+## Cross-Platform Validation Tasks
268
106
-### Always Test These After Changes:
107
-1. **Documentation Build**: Run `mkdocs build -f doc/mkdocs.yml` and verify no errors
108
-2. **Code Formatting**: Run `clang-format --dry-run --style=file` on changed files
109
-3. **Windows Build** (if on Windows): Full cmake build cycle
110
-4. **Distribution Validation**: Run Python validation scripts on any distribution changes
269
+### Documentation (Works on Linux/Windows)
270
+- Install tools: `pip install mkdocs-mermaid2-plugin mkdocs --break-system-packages`
271
+- Build docs: `mkdocs build -f doc/mkdocs.yml`
272
+- Output location: `doc/site/`
273
+- **Note**: May show warnings about mermaid CDN access on restricted networks
274
112
-### Manual Validation Requirements
113
-- **Windows builds**: Install MSI and test basic WSL functionality (`wsl --version`, `wsl -l`)
114
-- **Documentation changes**: Review generated HTML in `doc/site/`
115
-- **Distribution changes**: Test with actual WSL distribution installation
275
+### Code Formatting and Validation
276
+- Format all source (Windows, requires `cmake .` first): `.\FormatSource.ps1`
277
+- Format check (Linux/cross-platform): `clang-format --dry-run --style=file <files>`
278
+- Validate copyright headers: `python3 tools/devops/validate-copyright-headers.py`
279
+ - **Note**: Will report missing headers in generated/dependency files (`_deps/`), which is expected
280
+- Validate localization: `python3 tools/devops/validate-localization.py`
281
+ - **Note**: Only works after Windows build (requires `localization/strings/en-US/Resources.resw`)
282
117
-## Repository Navigation
283
+### Distribution Validation (Limited on Linux)
284
+- Validate distribution info: `python3 distributions/validate.py distributions/DistributionInfo.json`
285
+- **Note**: May fail on Linux due to network restrictions accessing distribution URLs
286
119
-### Key Directories
120
-- `src/windows/` - Main Windows WSL service components
121
-- `src/linux/` - Linux-side WSL components
122
-- `src/shared/` - Shared code between Windows and Linux
123
-- `test/windows/` - Windows-based tests (TAEF framework)
124
-- `test/linux/unit_tests/` - Linux unit test suite
125
-- `doc/` - Documentation source (MkDocs)
126
-- `tools/` - Build and deployment scripts
127
-- `distributions/` - Distribution validation and metadata
287
+### Pre-commit Checklist
288
+Always run before committing:
289
+1. `.\FormatSource.ps1` to verify formatting on changed C++ files
290
+2. `python3 tools/devops/validate-copyright-headers.py` (ignore `_deps/` warnings)
291
+3. `mkdocs build -f doc/mkdocs.yml` if documentation changed
292
+4. Full Windows build if core components changed
293
129
-### Key Files
130
-- `CMakeLists.txt` - Main build configuration
131
-- `doc/docs/dev-loop.md` - Developer build instructions
132
-- `test/README.md` - Testing framework documentation
133
-- `CONTRIBUTING.md` - Contribution guidelines
134
-- `.clang-format` - Code formatting rules
135
-- `UserConfig.cmake.sample` - Optional build customizations
294
+**Note**: The `.gitignore` properly excludes build artifacts (`*.sln`, `*.dll`, `*.pdb`, `obj/`, `bin/`, etc.) — do not commit these files.
295
137
-### Frequently Used Commands (Platform-Specific)
296
+## Frequently Used Commands
297
139
-#### Windows Development:
140
-```bash
298
+### Windows Development
299
+```powershell
300
# Initial setup
301
cmake .
143
-cmake --build . -- -m # 20-45 minutes, NEVER CANCEL
302
+cmake --build . -- -m
303
145
-# Deploy and test
304
+# Deploy and test
305
powershell tools\deploy\deploy-to-host.ps1
306
wsl --version
307
308
# Run tests
150
-bin\x64\debug\test.bat # 30-60 minutes, NEVER CANCEL
309
+bin\x64\debug\test.bat
310
```
311
153
-#### Cross-Platform Validation:
154
-```bash
155
-# Documentation (0.5 seconds)
312
+### Cross-Platform Validation
313
+```powershell
314
+# Documentation
315
mkdocs build -f doc/mkdocs.yml
316
158
-# Code formatting
159
-find src -name "*.cpp" -o -name "*.h" | xargs clang-format --dry-run --style=file
317
+# Code formatting (Windows)
318
+.\FormatSource.ps1
319
320
# Copyright header validation (reports expected issues in _deps/)
321
python3 tools/devops/validate-copyright-headers.py
@@ -171,7 +330,7 @@ python3 distributions/validate.py distributions/DistributionInfo.json
330
```powershell
331
# Collect traces
332
wpr -start diagnostics\wsl.wprp -filemode
174
-# [reproduce issue]
333
+# [reproduce issue]
334
wpr -stop logs.ETL
335
336
# Available profiles:
@@ -194,35 +353,28 @@ debugConsole=true
353
```
354
355
### Common Debugging Commands
197
-- Debug shell: `wsl --debug-shell`
356
+- Debug shell: `wsl --debug-shell`
357
- Collect WSL logs: `powershell diagnostics\collect-wsl-logs.ps1`
358
- Network logs: `powershell diagnostics\collect-wsl-logs.ps1 -LogProfile networking`
359
201
-## Critical Timing and Timeout Guidelines
360
+## Timing and Timeout Guidelines
361
203
-**NEVER CANCEL these operations - always wait for completion:**
362
+**NEVER CANCEL these operations — always wait for completion:**
363
205
-- **Full Windows build**: 20-45 minutes (set timeout: 60+ minutes)
206
-- **Full test suite**: 30-60 minutes (set timeout: 90+ minutes)
207
-- **Unit test subset**: 5-15 minutes (set timeout: 30+ minutes)
208
-- **Documentation build**: ~0.5 seconds (set timeout: 5+ minutes)
209
-- **Distribution validation**: 2-5 minutes (set timeout: 15+ minutes)
364
+| Operation | Typical Duration | Minimum Timeout |
365
+|---|---|---|
366
+| Full Windows build | 20-45 minutes | 60+ minutes |
367
+| Full test suite | 30-60 minutes | 90+ minutes |
368
+| Unit test subset | 5-15 minutes | 30+ minutes |
369
+| Documentation build | ~0.5 seconds | 5+ minutes |
370
+| Distribution validation | 2-5 minutes | 15+ minutes |
371
372
## CI/CD Integration
373
374
### GitHub Actions
214
-- **distributions.yml**: Validates distribution metadata (Linux)
215
-- **documentation.yml**: Builds and deploys docs (Linux)
216
-- **modern-distributions.yml**: Tests modern distribution support
217
-
218
-### Pre-commit Validation
219
-Always run before committing:
220
-1. `clang-format --dry-run --style=file` on changed C++ files
221
-2. `python3 tools/devops/validate-copyright-headers.py` (ignore _deps/ warnings)
222
-3. `mkdocs build -f doc/mkdocs.yml` if documentation changed
223
-4. Full Windows build if core components changed
224
-
225
-**Note**: The `.gitignore` file properly excludes build artifacts (*.sln, *.dll, *.pdb, obj/, bin/, etc.) - do not commit these files.
375
+- **distributions.yml** — Validates distribution metadata (Linux)
376
+- **documentation.yml** — Builds and deploys docs (Linux)
377
+- **modern-distributions.yml** — Tests modern distribution support
378
379
## Development Environment Setup
380
@@ -233,11 +385,10 @@ Always run before committing:
385
4. Clone repository
386
5. Run `cmake .` to generate solution
387
236
-### Linux (Documentation/Validation Only)
388
+### Linux (Documentation/Validation Only)
389
1. Install Python 3.8+
238
-2. Install clang-format
239
-3. Install docs tools: `pip install mkdocs-mermaid2-plugin mkdocs`
240
-4. Clone repository
241
-5. Run validation commands as needed
390
+2. Install docs tools: `pip install mkdocs-mermaid2-plugin mkdocs`
391
+3. Clone repository
392
+4. Run validation commands as needed
393
394
Remember: **This is a Windows-focused project**. While some tasks can be performed on Linux, full WSL development requires Windows with Visual Studio.
\ No newline at end of file
.github/copilot/commit.md
new
+8
@@ -0,0 +1,8 @@
1
+## Commit Message Guidelines for WSL
2
+
3
+This repo has no strict commit message format. Follow these general practices:
4
+
5
+- Write a concise summary under 72 characters
6
+- Use imperative mood ("Fix crash" not "Fixed crash")
7
+- Reference GitHub issues with `(#123)` or `Fixes #123`
8
+- Add a body paragraph for non-obvious changes explaining *why*
.github/copilot/review.md
new
+23
@@ -0,0 +1,23 @@
1
+## Code Review Guidelines for WSL
2
+
3
+When reviewing code, enforce the conventions in `.github/copilot-instructions.md`. Focus especially on these high-risk areas:
4
+
5
+### ABI Safety (Critical)
6
+- **Flag** new methods added to existing COM interfaces without a new versioned interface/IID
7
+- **Flag** changed struct layouts in IDL files
8
+- **Flag** changes to `WSLPluginHooksV1` or `WSLPluginAPIV1` structs (public API)
9
+
10
+### Resource Safety
11
+- **Flag** raw `CloseHandle()`, `delete`, `free()`, or manual resource cleanup — require WIL smart pointers
12
+- **Flag** missing `NON_COPYABLE()` / `NON_MOVABLE()` on classes that hold resources
13
+- **Flag** lock usage without `_Guarded_by_()` SAL annotations
14
+
15
+### User-Facing Changes
16
+- **Flag** hardcoded English strings — require `Localization::MessageXxx()` and Resources.resw entry
17
+- **Flag** new `.wslconfig` settings without corresponding Resources.resw localization string
18
+- **Flag** silent fallback on invalid config values — require `EMIT_USER_WARNING()`
19
+
20
+### Error Handling
21
+- **Flag** bare `if (FAILED(hr))` — require WIL macros
22
+- **Flag** silently swallowed errors — require `CATCH_LOG()` or `LOG_IF_FAILED()`
23
+- **Flag** telemetry events missing privacy data tags
.github/copilot/test.md
new
+96
@@ -0,0 +1,96 @@
1
+## Test Generation Guidelines for WSL
2
+
3
+When generating tests for this repository, follow these patterns:
4
+
5
+### Framework
6
+Tests use TAEF (Test Authoring and Execution Framework). Always include `"Common.h"`.
7
+
8
+### Test Class Structure
9
+```cpp
10
+#include "Common.h"
11
+
12
+namespace MyFeatureTests
13
+{
14
+class MyFeatureTests
15
+{
16
+ WSL_TEST_CLASS(MyFeatureTests)
17
+
18
+ TEST_CLASS_SETUP(TestClassSetup)
19
+ {
20
+ VERIFY_ARE_EQUAL(LxsstuInitialize(FALSE), TRUE);
21
+ return true;
22
+ }
23
+
24
+ TEST_CLASS_CLEANUP(TestClassCleanup)
25
+ {
26
+ LxsstuUninitialize(FALSE);
27
+ return true;
28
+ }
29
+
30
+ TEST_METHOD(DescriptiveTestName)
31
+ {
32
+ // Test implementation
33
+ }
34
+};
35
+}
36
+```
37
+
38
+### Key Rules
39
+- Use `WSL_TEST_CLASS(Name)` — never raw `BEGIN_TEST_CLASS`
40
+- Setup/cleanup methods must `return true` on success
41
+- Use `VERIFY_*` macros for assertions — never `assert()` or exceptions for test validation
42
+
43
+### Assertion Macros
44
+- `VERIFY_ARE_EQUAL(expected, actual)` — value equality
45
+- `VERIFY_ARE_NOT_EQUAL(a, b)` — value inequality
46
+- `VERIFY_IS_TRUE(condition)` — boolean check
47
+- `VERIFY_IS_FALSE(condition)` — negative boolean check
48
+- `VERIFY_IS_NULL(ptr)` — null check
49
+- `VERIFY_IS_NOT_NULL(ptr)` — non-null check
50
+- `VERIFY_WIN32_BOOL_SUCCEEDED(expr)` — Win32 BOOL result
51
+- `VERIFY_SUCCEEDED(hr)` — HRESULT success
52
+
53
+### Logging in Tests
54
+- `LogInfo(fmt, ...)` — informational messages
55
+- `LogError(fmt, ...)` — error messages
56
+- `LogWarning(fmt, ...)` — warnings
57
+- `LogPass(fmt, ...)` — explicit pass messages
58
+- `LogSkipped(fmt, ...)` — skip messages
59
+
60
+### Conditional Skipping
61
+Add skip macros at the start of a test method body when the test only applies to certain environments:
62
+```cpp
63
+TEST_METHOD(Wsl2SpecificTest)
64
+{
65
+ WSL2_TEST_ONLY();
66
+ // ... test code ...
67
+}
68
+```
69
+
70
+Available skip macros:
71
+- `WSL1_TEST_ONLY()` — skip unless WSL1
72
+- `WSL2_TEST_ONLY()` — skip unless WSL2
73
+- `SKIP_TEST_ARM64()` — skip on ARM64
74
+- `SKIP_TEST_UNSTABLE()` — skip known-flaky tests
75
+- `WINDOWS_11_TEST_ONLY()` — skip on pre-Windows 11
76
+- `WSL_TEST_VERSION_REQUIRED(version)` — skip if WSL version too old
77
+
78
+### RAII Test Helpers
79
+- `WslKeepAlive` — prevents UVM timeout during long-running tests; create at test start
80
+- `WslConfigChange` — RAII wrapper that applies a temporary `.wslconfig` and restores the original on destruction:
81
+```cpp
82
+TEST_METHOD(TestWithCustomConfig)
83
+{
84
+ WslConfigChange config(L"[wsl2]\nmemory=4GB\n");
85
+ // ... test with custom config ...
86
+ // Original .wslconfig restored when config goes out of scope
87
+}
88
+```
89
+
90
+### Memory in Tests
91
+- Use `ALLOC(size)` / `FREE(ptr)` macros for direct heap allocation in tests
92
+- Prefer RAII wrappers and smart pointers for production-like code paths
93
+
94
+### Test Naming
95
+- Use descriptive PascalCase names that describe the scenario: `CreateInstanceWithInvalidGuidFails`, `EchoTest`, `MountPlan9Share`
96
+- Group related tests in the same test class