forked from itod/yourbugreportsucks
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
159 lines (107 loc) · 6.25 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Your Bug Report Sucks</title>
<link rel="stylesheet" href="style.css" type="text/css" charset="utf-8">
<style type="text/css" media="screen">
#wrapper {
width:700px;
margin:30px auto 50px;
}
#credits {
font-size:11px;
text-align:center;
margin:30px auto 0px;
}
</style>
</head>
<body>
<div id="wrapper">
<h4 id="no_offense_but_your_bug_report_sucks">No offense, but your bug report sucks.</h4>
<p>Actually, I used to write really sucky bug reports myself. </p>
<p>But then I got a job as a lowly programmer at a certain fruit company, where internal bug reporting is taken fairly seriously. That’s where I learned how to write great bug reports.</p>
<p>I’d like to share what I’ve learned so you can write great bug reports too!</p>
<h4 id="why_should_i_care_about_writting_great_bug_reports_i_hear_you_say"><em>Why should I care about writting great bug reports?</em> I hear you say.</h4>
<p>You’ve taken the time to contact a devloper about a bug in their software. So, clearly, you want this bug to be squashed. The best thing you can do to help make that happen, is to write a great bug report. This will vastly increase the chances that the bug will be fixed in a timely manner.</p>
<p>And honestly, it only takes a few short minutes. <em>Turns Out</em>™, writing a great bug report is easy!</p>
<hr />
<h4 id="a_great_bug_report_always_contains_the_following_essential_parts">A great bug report always contains the following essential parts:</h4>
<ol>
<li>SUMMARY</li>
<li>SETUP</li>
<li>STEPS TO REPRODUCE</li>
<li>EXPECTED RESULT</li>
<li><p>ACTUAL RESULT</p>
<p><em>If you’re feeling especially helpful, one additional part is always appreciated:</em></p></li>
<li><p>ADDITIONAL NOTES (OPTIONAL)</p></li>
</ol>
<p>Let’s break these down.</p>
<ol>
<li><p>SUMMARY</p>
<p>A one (or maybe two) sentence, high-level description of the problem. This is almost like the subject line of an email.</p></li>
<li><p>SETUP</p>
<p>This is where you tell the developer about your setup. Three things are vital:</p>
<ol>
<li>The hardware device you’re using. (like <code>iPhone 5S</code>, or <code>2013 MacBookPro Retina</code>)</li>
<li>The OS version you’re using. (like <code>iOS 7.2</code>, or <code>OS X 10.9.4</code>)</li>
<li>The specific version of the app you’re using. Include build numbers if possible. (like <code>Mail.app Version 7.3 (1878.6)</code>, or <code>TextMate version 2.0-alpha.9551</code>)</li>
</ol>
<p>If you’re reporting a bug on a website, substitute <strong>the name and version of the web browser you are using</strong> for the app name and version.</p></li>
<li><p>STEPS TO REPRODUCE</p>
<p><strong>This is the most important part</strong>. Break the issue down into a specific numbered list of steps that always (or at least sometimes) reproduces the problem. </p>
<p>Seriously, break it down into a numbered list of steps. Here’s an example:</p>
<pre><code>1. Visit example.com in any browser listed in SETUP above. See normal "Home" page appear.
2. Click blue "compose" button. See "compose" text area appear
3. Type "hello world" in compose text area
etc…
</code></pre></li>
<li><p>EXPECTED RESULT</p>
<p>Sometimes the desired outcome you expect is not obvious to the developer. Just to be safe, spell it out here in one short sentence or phrase.</p></li>
<li><p>ACTUAL RESULT</p>
<p>This is what you’ve been waiting for. Here’s your chance to describe what is actually going wrong. Make this section as long and detailed as you like. In fact, rant away! Since you’ve already provided <strong>a numbered list of steps</strong> to reproduce the problem (you did provide a numbered list of steps, didn’t you?), you’re now free to complain all you like about what’s going wrong.</p>
<p>If the app crashes, describe that here, and include the entire crash log, please.</p>
<p><em>And finally, the optional part:</em></p></li>
<li><p>ADDITIONAL NOTES (OPTIONAL)</p>
<p>If you’re feeling especially helpful, fee free to provide additional info here. For example, if you know what version this issue first appeared in, please mention that here.</p>
<p>If you’re reporting a bug in a website, did you try to reproduce it in multiple browsers? (That’s always a great idea, BTW.) Great! Tell us about it here.</p>
<p>If you’re reporting a bug in a Mac app, did you simultaneously run Console.app and capture some suspicious-looking console logs? (That’s always a great idea, BTW.) Great! Tell us about it here.</p></li>
</ol>
Below is a template to get you started. Please copy and paste this into an email or your bug reporting sofware of choice and start from there.
That’s it! Thanks for reading, and happy bug reporting. :)
<hr />
<pre><code>SUMMARY
------------------
<REPLACE ME WITH A HIGH-LEVEL DESCRIPTION OF THE PROBLEM IN A SENTENCE OR TWO>
SETUP
------------------
Device: <DEVICE + VERSION HERE>
OS: <OS + VERSION HERE>
App: <APP OR BROWSER + VERSION NUMBER HERE>
STEPS TO REPRODUCE
------------------
1. <STEP ONE>
2. <STEP TWO>
3. <ETC>
EXPECTED RESULT
------------------
<WHAT DID YOU EXPECT>
ACTUAL RESULT
------------------
<WHAT WENT WRONG>
ADDITIONAL NOTES
------------------
<CRASH LOGS, CONSOLE ERROR MESSAGES, VERSION THIS FIRST APPEARED, AND OR OTHER OPTIONAL INFO>
</code></pre>
<div id="credits">
<p>Site by <a href="http://twitter.com/itod">Todd Ditchendorf</a> of <a href="http://celestialteapot.com">Celestial Teapot</a>.</p>
<p><a href="https://github.com/ttscoff/MarkedCustomStyles/blob/master/default_styles/github.css">Stylesheet</a> by <a href="http://brettterpstra.com/">Brett Terpstra</a>.</p>
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-53066460-1', 'auto');
ga('send', 'pageview');
</script>
</div>
</body>