How to test Ubuntu Focal Fossa on WSL: Reporting Bugs

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.

• If an application is failing to run, export an strace and upload to a saved to a pastebin or gist

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

/r/bashonubuntuonwindows

Bug reporting etiquette

Awesome-WSL

The Ubuntu lifecycle and release cadence