Update CONTRIBUTING.md
Jack Hammons committed
Jul 11, 2016 at 16:10 UTC
2ce04d0f1f674f9c089c09b9a16e1d513516315b
1 file changed
+67
-22
CONTRIBUTING.md
+67
-22
@@ -1,29 +1,74 @@
1
-When reporting a bug, please be sure post the following information:
1
+Please provide as much information as possible when reporting a bug or filing an issue on the Windows Subsystem for Linux.
2
+A well written bug will follow the template:
3
3
-1. The build of Windows you're running. Example:
4
-```cmd
5
-C:\Users\Dave>ver
4
+1) Issue Title
5
7
-Microsoft Windows [Version 10.0.14385]
8
-```
6
+2) Brief description
7
+Briefly describe what you are attemping to run.
8
+
9
+3) Windows version / build number
10
+Your Windows build number. This can be gathered from the CMD prompt using the `ver` command.
11
10
-2. The exact command you tried to run. Example:
11
-```cmd
12
-dave@remoteoffice2.nsa.gov:~$ ps aux
13
-Error: /proc must be mounted
14
- To mount /proc at boot you need an /etc/fstab line like:
15
- proc /proc proc defaults
16
- In the meantime, run "mount proc /proc -t proc"
12
```
13
+C:\>ver
14
+Microsoft Windows [Version 10.0.14385]
15
+```
16
+
17
+4) Commands required to reproduce the error
18
+Should include all packages required to install and configuration required.
19
+
20
+5) Copy of the terminal output
21
+
22
+6) Strace of the failing command
23
+Run the failing command under [strace] (http://manpages.ubuntu.com/manpages/wily/man1/strace.1.html). Normal command structure is:
24
+
25
+```
26
+$ strace <command>
27
+```
28
+
29
+Strace can produce a very long output. If this is more than about 20 lines please paste this into [Gist](https://gist.github.com/) or another paste service and link in the bug.
30
+
31
+7) Additional information
32
+Some bugs require additional information such as scripts to reproduce. Please add to this section.
33
+
34
+If there are files required, email the files to InsiderSupport@microsoft.com with:
35
+Subject: Forward to WSL Team - RE: github issue <issue #>
36
+Body: "Please forward to WSL Team" and include your attachment.
37
+
38
+Common files are:
39
+Memory dumps found under C:\Windows\MEMORY.DMP
40
+Additional strace logs if the error occurs within a fork. The following command generates an output file for every fork created:
41
19
-3. The strace log of the command that failed to run. Please paste this into [Gist](https://gist.github.com/) or another paste service. Example:
20
-```cmd
21
-dave@remoteoffice2.nsa.gov:~$ strace whoami
22
-execve("/usr/bin/whoami", ["whoami"], [/* 16 vars */]) = 0
23
-brk(NULL) = 0x2423000
42
+```
43
+$ strace -ff -o <outputfile> <command>
44
+```
45
+
46
+
47
+-- Example Bug
48
+
49
+1)`Traceroute not working.`
50
+2)`IP_MTU_DISCOVER error when running traceroute.`
51
+
52
+3)`Microsoft Windows [Version 10.0.14385]`
53
+
54
+4)`$ sudo apt-get install traceroute`
55
+`$ traceroute www.microsoft.com`
56
+
57
+5) Copy of the terminal output
58
+
59
+```russ@RUSSALEX-BOOK:/mnt/c$ traceroute www.microsoft.com
60
+traceroute to www.microsoft.com (23.75.239.28), 30 hops max, 60 byte packets
61
+setsockopt IP_MTU_DISCOVER: Invalid argument```
62
+
63
+6)
64
+```
65
+russ@RUSSALEX-BOOK:/mnt/c$ strace traceroute www.microsoft.com
66
+execve("/usr/bin/traceroute", ["traceroute", "www.microsoft.com"], [/* 22 vars */]) = 0
67
+brk(0) = 0x7fffdd3bc000
68
access("/etc/ld.so.nohwcap", F_OK) = -1 ENOENT (No such file or directory)
25
-.... this file will be very large ....
26
-close(2) = 0
27
-exit_group(0) = ?
28
-+++ exited with 0 +++
69
+mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f1f4e820000
70
+access("/etc/ld.so.preload", R_OK) = -1 ENOENT (No such file or directory)
71
+...
72
+...
73
+...
74
```