Modernize the bug reporting guidelines and make them a little less Mac-specific.
Reviewed by Dan Bernstein.
* quality/bugwriting.html:
git-svn-id: http://svn.webkit.org/repository/webkit/trunk@35929 268f45cc-cd09-0410-ab3c-d52691b4dbfc
diff --git a/WebKitSite/ChangeLog b/WebKitSite/ChangeLog
index 13f0f20..da47774 100644
--- a/WebKitSite/ChangeLog
+++ b/WebKitSite/ChangeLog
@@ -1,3 +1,11 @@
+2008-08-25 Mark Rowe <mrowe@apple.com>
+
+ Reviewed by Dan Bernstein.
+
+ Modernize the bug reporting guidelines and make them a little less Mac-specific.
+
+ * quality/bugwriting.html:
+
2008-08-18 Mark Rowe <mrowe@apple.com>
Upgrade to WordPress 2.6.1.
diff --git a/WebKitSite/quality/bugwriting.html b/WebKitSite/quality/bugwriting.html
index 6c66f40..8a017d3 100644
--- a/WebKitSite/quality/bugwriting.html
+++ b/WebKitSite/quality/bugwriting.html
@@ -1,8 +1,8 @@
<?php
- $title = "Bug Report Guidelines";
+ $title = "Bug Reporting Guidelines";
include("../header.inc");
?>
-<h2>Bug Report Guidelines</h2>
+<h2>Bug Reporting Guidelines</h2>
<p>This document describes how to write a good WebKit bug report. Good bug reports help developers and quality assurance (QA) people decide
an appropriate priority and severity for a bug, and increase the chance that a bug will be fixed quickly. The more specific information
@@ -11,22 +11,17 @@
<ol>
<li><b>Version</b>
<p>
- Please select the WebKit version you were using when the bug occurred, or the closest match. <tt>312</tt> is the WebKit version
- that shipped with Mac OS X 10.3.9. <tt>412</tt> up to <tt>418.8</tt> are the WebKit versions that shipped with Mac OS X 10.4 (Tiger)
- and it's updates.
+ Please select the WebKit version you were using when the bug occurred, or the closest matching version.
</p>
<p>
- Locally-built versions of WebKit have a <tt>+</tt> after the build number, and their build number is generally higher
- then the latest release version. So, for example, <tt>420+</tt> is a
- locally-built version of WebKit that's newer than the <tt>418.8</tt> version that shipped with the latest update of Tiger.
+ Versions of WebKit that are not part of a Safari release have a <tt>+</tt> after the version number, and their version number
+ is generally higher then the latest released version of WebKit. So, for example, <tt>528+</tt> is an unofficial build of WebKit
+ that is newer than the <tt>525.x</tt> version that shipped as part of Safari 3.1.2.
</p>
<div style="display: none; text-align: center; font-weight: bold;" id="webkit_version"></div>
<script type="text/javascript">
- var regex;
- var matches;
-
- regex = new RegExp("Mozilla/5.0 \\(.*\\) AppleWebKit/(.*) \\(KHTML, like Gecko\\) Safari/(.*)");
- matches = regex.exec(navigator.userAgent);
+ var regex = new RegExp("AppleWebKit/(.*?)( |$)");
+ var matches = regex.exec(navigator.userAgent);
if (matches)
{
var webKitVersion = document.getElementById('webkit_version');
@@ -35,24 +30,24 @@
versionNumber.appendChild(document.createTextNode(matches[1]));
webKitVersion.appendChild(versionNumber);
webKitVersion.style.display = "block";
-
- webKitVersion = parseInt(matches[1]);
}
</script>
- <li><b>Component</b>
- <p>If you know the precise cause of a bug (i.e., you've reduced it to a failing test case and know the reason), then you can
- assign a bug to a specific component such as <tt>CSS</tt> or <tt>HTML Editing</tt>.
- <p>If, however, there is any doubt in your mind as to the cause of the bug, then file it under <tt>New Bugs</tt>. This component
- is the place for any bugs whose cause has not yet been determined. Once someone has reduced the bug and knows the cause, then it
- will be moved from the <tt>New Bugs</tt> component to the appropriate place.</p>
+ <li><b>Component</b>
+ <p>If you know the precise cause of a bug (i.e., you've reduced it to a failing test case and know the reason), then you can
+ assign a bug to a specific component such as <tt>CSS</tt> or <tt>HTML Editing</tt>.
+ <p>If, however, there is any doubt in your mind as to the cause of the bug, then file it under <tt>New Bugs</tt>. This component
+ is the place for any bugs whose cause has not yet been determined. Once someone has reduced the bug and knows the cause, then it
+ will be moved from the <tt>New Bugs</tt> component to the appropriate place.</p>
</li>
<li>
<b>Platform and OS</b>
- <p>Please select the platform and the OS version that your bug occurred on. Typically this would be platform <tt>Macintosh</tt>
- and OS <tt>Mac OS X 10.3</tt> (Panther) or <tt>Mac OS X 10.4</tt> (Tiger). </p>
- </li>
+ <p>Please select the platform and the OS version that your bug occurred on. If you're running on Mac OS X this would often be platform
+ <tt>Macintosh</tt> and OS <tt>Mac OS X 10.5</tt> (Leopard). If you're running on Windows or Linux, please select <tt>PC</tt> for platform
+ and the appropriate entry from the OS field. If your exact system is not listed, please select the closest entry and provide further
+ details in the description of the bug report.
+ </li>
<li>
<b>Priority</b>
@@ -67,7 +62,7 @@
<tt>enhancement</tt>, it's helpful to specify that value. A QA person or developer will set this to some other value if
appropriate.</p>
</li>
-
+
<li><b>URL</b>
<p>Fill in this field with the URL of a page that shows the bug, when possible. If you have created a <a href="reduction.html">test case reduction</a> for the bug,
please add it to the bug report as an attachment rather than putting it on a web server and listing its URL here. Doing so
@@ -75,32 +70,35 @@
</li>
<li><b>Summary</b>
- <p>A good summary explains the problem in clear and specific terms, but is often concise enough to fit within the default summary space in Bugzilla.
+ <p>A good summary explains the problem in clear and specific terms, but is often concise enough to fit within the default summary space in Bugzilla.
One should be able to tell exactly what a bug is about just by reading the summary.</p>
-
+
Tips for a good summary:
<ul>
- <li>include the domain of the page that shows the bug (especially if it's an important site)
- <li>if the bug is a crash, note this and note whether or not the crash is reproducible
- <li>if you have tested and verified that this is a regression from a previous version of WebKit, prepend "REGRESSION" to the summary
- <li>if you know between which versions of WebKit the regression occurred, add this to the summary after REGRESSION (i.e., "REGRESSION (125-408)")
+ <li>Include the domain of the page that shows the bug (especially if it's an important site)
+ <li>If the bug is a crash, note this and note whether or not the crash is reproducible
+ <li>If you have tested and verified that this is a regression from a previous version of WebKit, prepend "REGRESSION: " to the summary
+ <li>If you know the range of revisions in which the regression occurred, add this to the summary after REGRESSION (i.e., "REGRESSION(r31201-r31211):")
</ul>
- </li>
-
- <li><b>Description</b>
+ </li><br>
+
+ <li><b>Description</b>
<p>In this field, write a more detailed explanation of the problem.</p>
-
+
Tips for Descriptions:
- <ul> <li> Please do not include more than one bug in one bug report. </li>
- <li> If you can only reproduce the problem on a version of WebKit that you built yourself, include the date that you checked out the source code. </li>
- <li> If there is no simple URL to a page that shows the bug (for instance, you have to click through multiple pages for the bug to occur), then describe the exact navigation required to reach the page where the bug occurs. Don't just say "go to the forums"; use detailed steps. </li>
- <li> Look at Console and include any messages that might be relevant in the bug. </li>
- <li> Include <a href="crashlogs.html">the backtrace</a> if you get a crash, if possible. File the bug first and then add the backtrace as an attachment.</li>
- <li> Include a screenshot for visual bugs. If the problem isn't very obvious, include a single screenshot which shows both correct and
- incorrect renderings, for example Safari and another browser such as Firefox or Mac IE. Use Grab.app or cmd-shift-4 and grab as small an area as possible that demonstrates the problem. Then attach the screenshot to the bug. </li>
- <li> Be as specific as possible. For instance, if you're describing a problem that occurs while scrolling, note in the bug whether you're scrolling with arrow keys, arrow buttons, scroll thumb, clicking above or below the thumb, scroll-wheel mouse, etc. </li>
- </ul><br>
-
+ <ul>
+ <li>Do not include more than one bug in one bug report.</li>
+ <li>If you built WebKit yourself or used a nightly build, include the SVN revision number as well as information about if you are using WebKit with Qt, GTK+, wxWidgets, etc.</li>
+ <li>If loading a single URL is not enough to show the bug (for instance, you have to click through multiple pages for the bug to occur), then describe the exact navigation required to reach the page where the bug occurs. Don't just say "go to the forums"; use detailed steps.</li>
+ <li>Look at the system console and include any messages that might be relevant in the bug.</li>
+ <li>Include <a href="crashlogs.html">the backtrace</a> if you get a crash, if possible. File the bug first and then add the backtrace as an attachment.</li>
+ <li>Include a screenshot for visual bugs. If the problem isn't very obvious, include a single screenshot which shows both correct and incorrect renderings,
+ for example Safari and another browser such as Firefox or Internet Explorer. On the Mac you can use Grab.app or Cmd-Shift-4 and capture a snap that demonstrates
+ the problem. You can then attach the screenshot to the bug.</li>
+ <li>Be as specific as possible. For instance, if you're describing a problem that occurs while scrolling, note in the bug whether you're scrolling with arrow
+ keys, arrow buttons, scroll thumb, clicking above or below the thumb, scroll-wheel mouse, etc.</li>
+ </ul></li><br>
+
<li>
<b>Depends on</b>
<p>If the fix for this bug depends on another bug fix, put the other bug's number here. Otherwise, leave it empty.</p>
