| 1 | # WSL contributing guide |
| 2 | |
| 3 | There are a few main ways to contribute to WSL, with guides to each one: |
| 4 | |
| 5 | 1. [Add a feature or bugfix to WSL](#add-a-feature-or-bugfix-to-wsl) |
| 6 | 2. [File a WSL issue](#file-a-wsl-issue) |
| 7 | |
| 8 | ## Add a feature or bugfix to WSL |
| 9 | |
| 10 | We welcome any contributions to the WSL source code to add features or fix bugs! Before you start actually working on the feature, please **[file it as an issue, or a feature request in this repository](https://github.com/microsoft/WSL/issues)** so that we can track it and provide any feedback if necessary. |
| 11 | |
| 12 | Once you have done so, please see [the developer docs](./doc/docs/dev-loop.md) for instructions on how to build WSL locally on your machine for development. |
| 13 | |
| 14 | When your fix is ready, please [submit it as a pull request in this repository](https://github.com/microsoft/WSL/pulls) and the WSL team will triage and respond to it. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com. |
| 15 | |
| 16 | ## File a WSL issue |
| 17 | |
| 18 | You can file issues for WSL at the WSL repository, or linked repositories. Before filing an issue please search for any existing issues and upvote or comment on those if possible. |
| 19 | |
| 20 | 1. If your issue is related to WSL documentation, please file it at [microsoftdocs/wsl](https://github.com/microsoftdocs/WSL/issues) |
| 21 | 2. If your issue is related to a Linux GUI app, please file it at [microsoft/wslg](https://github.com/microsoft/wslg/issues) |
| 22 | 3. Otherwise, if you have a technical issue related to WSL in general, such as start up issues, etc., please file it at [microsoft/wsl](https://github.com/microsoft/WSL/issues) |
| 23 | |
| 24 | ### Localization and translation issues |
| 25 | |
| 26 | If you spot a bad, missing, or incorrect translation in WSL's UI, **please file an issue** describing the problem (which language, what string, and what it should say) rather than opening a pull request. |
| 27 | |
| 28 | WSL's localized files are generated by a separate localization team and are regenerated downstream, so any translation edits made in a pull request here would be overwritten and cannot be merged. This covers the per-locale UI strings (`localization/strings/<locale>/Resources.resw`) and the per-locale Intune/group-policy templates (`intune/<locale>/WSL.adml`). Filing an issue lets us route the fix to the team that owns those translations. The `en-US` source files (`localization/strings/en-US/Resources.resw`, `intune/en-US/WSL.adml`, and the language-neutral `intune/WSL.admx`) are the exception, since those originate in this repository. This guidance does not apply to automated localization-service pull requests that are generated by that pipeline. |
| 29 | |
| 30 | Please provide as much information as possible when reporting a bug or filing an issue on the Windows Subsystem for Linux, and be sure to include logs as necessary! |
| 31 | |
| 32 | Please see the [notes for collecting WSL logs](#notes-for-collecting-wsl-logs) section below for more info on filing issues. |
| 33 | |
| 34 | ## Thank you |
| 35 | |
| 36 | Thank you in advance for your contribution! We appreciate your help in making WSL a better tool for everyone. |
| 37 | |
| 38 | ## Notes for collecting WSL logs |
| 39 | |
| 40 | ### Important: Reporting BSODs and Security issues |
| 41 | **Do not open GitHub issues for Windows crashes (BSODs) or security issues.** Instead, report the issue on the [Microsoft Researcher Portal](https://msrc.microsoft.com/report/vulnerability/new). |
| 42 | See the `10) Reporting a Windows crash (BSOD)` section below for detailed instructions. |
| 43 | |
| 44 | ### Reporting issues in Windows Console or WSL text rendering/user experience |
| 45 | Note that WSL distro's launch in the Windows Console (unless you have taken steps to launch a 3rd party console/terminal). Therefore, *please file UI/UX related issues in the [Windows Console issue tracker](https://github.com/microsoft/console)*. |
| 46 | |
| 47 | ### Collect WSL logs for networking issues |
| 48 | |
| 49 | Install iptables and tcpdump in your WSL distribution using the following commands. |
| 50 | Note: This will not work if WSL has Internet connectivity issues. |
| 51 | |
| 52 | ``` |
| 53 | # sudo apt-get update |
| 54 | # sudo apt-get -y install iptables tcpdump |
| 55 | ``` |
| 56 | |
| 57 | Install [WPR](https://learn.microsoft.com/windows-hardware/test/wpt/windows-performance-recorder) |
| 58 | |
| 59 | To collect WSL networking logs, do the following steps in an administrative powershell prompt: |
| 60 | |
| 61 | ``` |
| 62 | Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1 |
| 63 | Set-ExecutionPolicy Bypass -Scope Process -Force |
| 64 | .\collect-wsl-logs.ps1 -LogProfile networking |
| 65 | ``` |
| 66 | The script will output when log collection starts. Reproduce the problem, then press any key to stop the log collection. |
| 67 | The script will output the path of the log file once done. |
| 68 | |
| 69 | For additional network creation logs (restarts WSL), use: |
| 70 | ``` |
| 71 | .\collect-wsl-logs.ps1 -LogProfile networking -RestartWslReproMode |
| 72 | ``` |
| 73 | |
| 74 | <!-- Preserving anchors --> |
| 75 | <div id="8-detailed-logs"></div> |
| 76 | <div id="9-networking-logs"></div> |
| 77 | <div id="8-collect-wsl-logs-recommended-method"></div> |
| 78 | |
| 79 | |
| 80 | ### Collect WSL logs (recommended method) |
| 81 | |
| 82 | If you choose to email these logs instead of attaching them to the bug, please send them to wsl-gh-logs@microsoft.com with the GitHub issue number in the subject, and include a link to your GitHub issue comment in the message body. |
| 83 | |
| 84 | To collect WSL logs, download and execute [collect-wsl-logs.ps1](https://github.com/Microsoft/WSL/blob/master/diagnostics/collect-wsl-logs.ps1) in an administrative powershell prompt: |
| 85 | |
| 86 | ``` |
| 87 | Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1 |
| 88 | Set-ExecutionPolicy Bypass -Scope Process -Force |
| 89 | .\collect-wsl-logs.ps1 |
| 90 | ``` |
| 91 | The script will output the path of the log file once done. |
| 92 | |
| 93 | The collected logs include WSLg (graphical and audio application) logs from `/mnt/wslg`, so the same script covers graphical-app issues. WSLg crash dumps are included when the script is run with `-Dump`. |
| 94 | |
| 95 | For specific scenarios, you can use different log profiles: |
| 96 | - `.\collect-wsl-logs.ps1 -LogProfile storage` - Enhanced storage tracing |
| 97 | - `.\collect-wsl-logs.ps1 -LogProfile networking` - Comprehensive networking tracing (includes packet capture, tcpdump, etc.) |
| 98 | - `.\collect-wsl-logs.ps1 -LogProfile networking -RestartWslReproMode` - Networking tracing with WSL restart for network creation logs |
| 99 | - `.\collect-wsl-logs.ps1 -LogProfile hvsocket` - HvSocket-specific tracing |
| 100 | |
| 101 | ### 10) Reporting a Windows crash (BSOD) |
| 102 | |
| 103 | To collect a kernel crash dump, first run the following command in an elevated command prompt: |
| 104 | |
| 105 | ``` |
| 106 | reg.exe add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CrashControl /v AlwaysKeepMemoryDump /t REG_DWORD /d 1 /f |
| 107 | ``` |
| 108 | |
| 109 | Then reproduce the issue, and let the machine crash and reboot. |
| 110 | |
| 111 | After reboot, the kernel dump will be in `%SystemRoot%\MEMORY.DMP` (unless this path has been overridden in the advanced system settings). |
| 112 | |
| 113 | Please upload the kernel dump on the [Microsoft Researcher Portal](https://msrc.microsoft.com/report/vulnerability/new) |
| 114 | |
| 115 | Make sure that the description contains: |
| 116 | |
| 117 | - The GitHub issue number, if any |
| 118 | - That this dump is intended for the WSL team |
| 119 | |
| 120 | ### 11) Reporting a WSL process crash |
| 121 | |
| 122 | The easiest way to report a WSL process crash is by [collecting a user-mode crash dump](https://learn.microsoft.com/windows/win32/wer/collecting-user-mode-dumps). |
| 123 | |
| 124 | To collect dumps of all running WSL processes, please open a PowerShell prompt with admin privileges, navigate to a folder where you'd like to put your log files and run these commands: |
| 125 | |
| 126 | ``` |
| 127 | Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1 |
| 128 | Set-ExecutionPolicy Bypass -Scope Process -Force |
| 129 | .\collect-wsl-logs.ps1 -Dump |
| 130 | ``` |
| 131 | |
| 132 | The script will output the path to the log file when it is done. |
| 133 | |
| 134 | #### Enable automatic crash dump collection |
| 135 | |
| 136 | If your crash is sporadic or hard to reproduce, please enable automatic crash dumps to catch logs for this behavior: |
| 137 | |
| 138 | ``` |
| 139 | md C:\crashes |
| 140 | reg.exe add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /f |
| 141 | reg.exe add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /v DumpFolder /t REG_EXPAND_SZ /d C:\crashes /f |
| 142 | reg.exe add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /v DumpType /t REG_DWORD /d 2 /f |
| 143 | ``` |
| 144 | |
| 145 | Crash dumps will then automatically be written to C:\crashes. |
| 146 | |
| 147 | Once you're done, crash dump collection can be disabled by running the following command in an elevated command prompt: |
| 148 | |
| 149 | ``` |
| 150 | reg.exe delete "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /f |
| 151 | ``` |
| 152 | |
| 153 | ### 12) Collect wslservice time travel debugging traces |
| 154 | |
| 155 | To collect time travel debugging traces: |
| 156 | |
| 157 | 1) [Install WinDbg preview](https://apps.microsoft.com/store/detail/windbg-preview/9PGJGD53TN86?hl=en-us&gl=us&rtc=1) |
| 158 | |
| 159 | 2) Open WinDbg preview as administrator by running `windbgx` in an elevated command prompt |
| 160 | |
| 161 | 3) Navigate to `file` -> `Attach to process` |
| 162 | |
| 163 | 4) Check `Record with Time Travel Debugging` (at the bottom right) |
| 164 | |
| 165 | 4) Check `Show processes from all users` (at the bottom) |
| 166 | |
| 167 | 5) Select `wslservice.exe`. Note, if wslservice.exe is not running, you make it start it with: `wsl.exe -l` |
| 168 | |
| 169 | 6) Click `Configure and Record` (write down the folder you chose for the traces) |
| 170 | |
| 171 | 7) Reproduce the issue |
| 172 | |
| 173 | 8) Go back to WinDbg and click `Stop and Debug` |
| 174 | |
| 175 | 9) Once the trace is done collecting, click `Stop Debugging` and close WinDbg |
| 176 | |
| 177 | 10) Go to the folder where the trace was collected, and locate the .run file. It should look like: `wslservice*.run` |
| 178 | |
| 179 | 11) Share that file on the issue |