How to test Ubuntu Focal Fossa on WSL: Reporting Bugs
How to triage and report bugs properly on Ubuntu on WSL.
So you've run into a bug while testing Ubuntu Focal Fossa on WSL, now what?
Basic Steps
This applies to any WSL-related issue:
- Did you consult the documentation, such as the Ubuntu Wiki or Microsoft Docs.
- Did you Google the error message?
- Did you search the WSL GitHub issues for the error or name of the application you are having problems with?
- Did you Google the name of the application you are having problems with + " WSL"?
The Sorting Hat
To determine where to submit a bug, we must figure out what is breaking:
If it is an issue when running wslusc, wslsys, wslfetch, wslvar, or wslview, then report it as a bug on the Ubuntu version of wslutilities.
If it is a security issue, such as a privilege escalation, malware, Windows Defender-related, or results in a Green Screen of Death, then e-mail your bug report to secure@microsoft.com.
If it is an issue when upgrading from 18.04 or using apt on 20.04, then report it as a general Ubuntu WSL bug.
If it is an issue with the new Windows Terminal, such as rendering issues or mouse supports, then report it as a Terminal bug.
If it is an issue with WSL networking, Linux/Windows interoperability, or running binaries on WSL1, and can be reproduced on different WSL distros, then report it as a general WSL bug.
Help Us Help You
There is nothing more frustrating then getting a bug report from a user that is clearly upset but doesn't provide us enough information to help them. It is also not uncommon to have a user report a bug, have it get closed, and the user not understand why or feel like they were short-changed by the maintainer.
Here are some key things we need from you as maintainers when you are filing a bug report:
- You need to search for the problem first, both in the respective bug reports and on Google.
- You need to attempt some troubleshooting and information gathering yourself.
- You should provide a full and detailed bug report.
- You may need to be patient as bugs are investigated and sorted.
We need to know specifically for WSL:
- A title succinctly describing the issue
- Your version and build of Windows
ver.exe
- Your version of WSL
wsl.exe --list --all --verbose
- Steps to reproduce
1. Download Ubuntu from Microsoft Store
2. sudo apt install hello-world
3. hello-world
The goal here is to provide a minimal, complete, and verifiable example of the problem that can be reproduced by our engineers.
- What you expect to happen
An explanation of what you expected to happen here. For example, hello-world returned 'Hello World!'
- What actually happens
An explanation of what is happening here instead. For example, hello-world segfaults.
strace -o some_command.strace -f some_command some_args
- A list of what you have attempted to do so solve or document the bug, including workarounds
Other helpful information you can include:
- Name of the package involved, e.g. ebtables
- A screenshot of the error using the Snipping Tool or Snip & Sketch in Action Center
- Logs saved to a Pastebin or Github Gist
- If you are having problems launching WSL, more detailed logs may be necessary
- A temporary workaround you found
This information and some patience will allow us to better serve our users when bugs arise.
Additional tips:
- Limit each report to one issue at a time
- Use bullet points to summarize
- Do not lost lengthy logs in your report, use a Pastebin or Github Gist
- Use code snippets and formatting where needed to improve readability
- Use footnotes [1] for lengthy digressions
More resources:
##windows-wsl on Freenode IRC