head	1.5;
access;
symbols
	TIGRIS_1_1_0RC2:1.3
	TIGRIS_1_1_0RC1:1.3
	TIGRIS_1_1:1.3.0.4
	TIGRIS_1_0_8:1.3
	TIGRIS_1_0_8RC3:1.3
	TIGRIS_1_0_8RC2:1.3
	TIGRIS_1_0_8RC1:1.3
	TIGRIS_1_0_7:1.3
	TIGRIS_1_0_7RC3:1.3
	TIGRIS_1_0_7RC2:1.3
	TIGRIS_1_0_7RC1:1.3
	TIGRIS_1_0_6:1.3
	TIGRIS_1_0_6RC5:1.3
	TIGRIS_1_0_6RC4:1.3
	TIGRIS_1_0_6RC3:1.3
	TIGRIS_1_0_6RC2:1.3
	TIGRIS_1_0_6RC1:1.3
	TIGRIS_1_0_5:1.3
	TIGRIS_1_0_5RC6:1.3
	TIGRIS_1_0_5RC5:1.3
	TIGRIS_1_0_5RC4:1.3
	TIGRIS_1_0_5RC3:1.3
	TIGRIS_1_0_5RC2:1.3
	TIGRIS_1_0_5RC1:1.3
	TIGRIS_1_0_4:1.3
	TIGRIS_1_0_3:1.3
	TIGRIS_1_0_2:1.3
	TIGRIS_1_0_1:1.3
	TIGRIS_1_0:1.3.0.6
	TIGRIS_1_0_0:1.3
	TIGRIS_1_0_0_RC1:1.3.0.2
	dlr:1.1.1
	TIGRIS_0_9_2_4:1.1
	TIGRIS_0_9_2_3:1.1
	HELM_PEER_PORT_BRANCH:1.1.1.1
	TURBINE_PEER:1.1
	TIGRIS_0_9_2_1:1.1
	TIGRIS_0_9_2:1.1.0.6
	TIGRIS_0_8_4:1.1.0.4
	TIGRIS_0_9_0:1.1.0.2;
locks; strict;
comment	@# @;


1.5
date	2001.06.21.07.07.40;	author jefflove;	state Exp;
branches;
next	1.4;

1.4
date	2001.06.11.03.14.33;	author jefflove;	state Exp;
branches;
next	1.3;

1.3
date	2001.03.16.23.50.12;	author lori;	state Exp;
branches;
next	1.2;

1.2
date	2001.02.11.18.29.47;	author jrobbins;	state Exp;
branches;
next	1.1;

1.1
date	2000.12.30.23.22.01;	author jrobbins;	state Exp;
branches
	1.1.1.1
	1.1.4.1
	1.1.8.1;
next	;

1.1.1.1
date	2001.02.21.00.32.02;	author dlr;	state Exp;
branches;
next	;

1.1.4.1
date	2001.01.16.00.17.44;	author susank;	state Exp;
branches;
next	;

1.1.8.1
date	2001.02.17.18.39.16;	author edk;	state Exp;
branches;
next	;


desc
@@


1.5
log
@html usage revision
@
text
@  <div class="docs" id="issuewritinghelp">
   <h2>Issue writing guidelines</h2>

   <div class="toc">
    <h3>Additional resources about issues: Index</h3>

    <ul>
     <li>
      <a href="ProjectIssues.html">Project Issues help</a> 

      <ul>
       <li><a href="issue_lifecycle.html">The issue life cycle</a></li>

       <li><strong>You are here:</strong> Issue writing guidelines</li>

       <li><a href="issuezilla_tipsandtricks.html">IssueZilla tips and tricks</a></li>

       <li><a href="contributing_patches.html">Contributing patches</a></li>
      </ul>
     </li>
    </ul>
   </div>

   <div class="courtesylinks">
    <p><a href="/servlets/HelpTOC">Back to main Help index</a></p>
   </div>

   <h3>Why you should read this</h3>

   <p>Simply put, the more effectively you report an issue, the more likely an engineer will actually fix it.</p>

   <p>These issue writing guidelines are an attempt at a general tutorial on writing effective issue reports for novice issue writers; not every sentence may precisely apply to your software project.</p>

   <h3>How to write a useful issue report</h3>

   <p>Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:</p>

   <ol>
    <li>
     <h3>Reproducible.</h3>

     <p>If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it "WORKSFORME" or "INVALID", and move on to the next issue. Every detail you can provide helps.</p>
    </li>

    <li>
     <h3>Specific.</h3>

     <p>The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed.(If a programmer or tester has to decipher an issue, they spend more time cursing the submitter than fixing or testing the problem.)</p>
    </li>
   </ol>

   <p>Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up an issue report:</p>

   <h3>BAD:</h3>

   <p>"My browser crashed. I think I was on foo.com. My computer uses Windows. I think that this is a really bad problem and you should fix it now. By the way, your icons really suck. Nobody will use your software if you keep those ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all messed up. Good luck."</p>

   <h3>GOOD:</h3>

   <p>"I crashed each time when I went to foo.com, using the 10.28.99 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced this problem using the 10.28.99 Linux build.</p>

   <p>It again crashed each time upon drawing the Foo banner at the top of the page. I broke apart the page, and discovered that the following image link will crash the application reproducibly, unless you remove the "border=0" attribute:</p>

   <p>&lt;IMG SRC="http://foo.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News"&gt;"</p>

   <h3>How to Enter your Useful Issue Report into IssueZilla:</h3>

   <p>Before you enter your issue, use the IssueZilla Query Page to determine whether the defect you've discovered is a known issue, and has already been reported. (If your issue is the 37th duplicate of a known issue, you're more likely to annoy the engineer. Annoyed engineers fix fewer issues.)</p>

   <p>Next, be sure that you've reproduced your issue using a recent build. (Engineers tend to be most interested in problems afflicting the code base that they're actively working on, rather than those in a code base that's hundreds of issue fixes obsolete.)</p>

   <p>If you've discovered a new issue using a current build, report it in IssueZilla:</p>

   <ol>
    <li>From your IssueZilla main page, choose "Enter a new issue".</li>

    <li>Select the product that you've found an issue in.</li>

    <li>Enter your e-mail address, password, and press the "Login" button. (If you don't yet have a password, leave the password text box empty, and press the "E-mail me a password" button instead. You'll receive an E-mail message with your password shortly.)</li>
   </ol>

   <p>Now, fill out the form. Here's what it all means:</p>

   <h3>Where did you find the issue?</h3>

   <h4>Product: In which product did you find the issue?</h4>

   <p>You just filled this out on the last page.</p>

   <h4>Version: In which product version did you find the issue?</h4>

   <p>If applicable.</p>

   <h4>Component: In which component does the issue exist?</h4>

   <p>IssueZilla requires that you select a component to enter an issue. (If they all look meaningless, click on the Component link, which links to descriptions of each component, to help you make the best choice.)</p>

   <h4>Platform: On which hardware platform did you find this issue?</h4>

   <p>(e.g., Macintosh, SGI, Sun, PC.) If you know the issue happens on all hardware platforms, choose 'All'. Otherwise, select the platform that you found the issue on, or "Other" if your platform isn't listed.</p>

   <h4>OS: On which Operating System (OS) did you find this issue?</h4>

   <p>(e.g., Linux, Windows NT, Mac OS 8.5.) If you know the issue happens on all operating systems, choose 'All'. Otherwise, select the OS that you found the issue on, or "Other" if your OS isn't listed.</p>

   <h3>How important is the issue?</h3>

   <h4>Issue Type: Is this a defect, enhancement, feature-request, or task?</h4>

   <p>This item defaults to 'defect'. (To determine the most appropriate type of issue, click on the Issue Type link for a full explanation of each choice.)</p>

   <h3>Who will be following up on the issue?</h3>

   <h4>Assigned To: Which engineer should be responsible for fixing this issue?</h4>

   <p>IssueZilla will automatically assign the issue to a default engineer upon submitting an issue report; the text box exists to allow you to manually assign it to a different engineer. (To see the list of default engineers for each component, click on the Component link.)</p>

   <h3>Cc: Who else should receive e-mail updates on changes to this issue?</h3>

   <p>List the full e-mail addresses of other individuals who should receive an e-mail update upon every change to the issue report. You can enter as many e-mail addresses as you'd like; e-mail addresses must be separated by commas, with no spaces between the addresses.</p>

   <h3>What else can you tell the engineer about the issue?</h3>

   <h4>URL: On what URL did you discover this issue?</h4>

   <p>If you encountered the issue on a particular URL, please provide it (or, them) here. If you've isolated the issue to a specific HTML snippet, please also provide a URL for that, too.</p>

   <h3>Summary:</h3>

   <h4>How would you describe the issue, in approximately 60 or fewer characters?</h4>

   <p>A good summary should <em>quickly and uniquely identify an issue report</em>. Otherwise, developers cannot meaningfully query by issue summary, and will often fail to pay attention to your issue report when reviewing a 10 page issue list.</p>

   <p>A summary of "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C" is a useful title. "Software fails" or "install problem" would be examples of a bad title.</p>

   <h3>Description: What else can you tell the engineer about this issue?</h3>

   <p>Please provide as detailed of a problem diagnosis in this field as possible.</p>

   <p>Where applicable, using the following issue report template will help ensure that all relevant information comes through:</p>

   <h4>Overview Description:</h4>

   <p>More detailed expansion of summary.</p>
<pre>
Drag-selecting any page crashes Mac builds in NSGetFactory
</pre>

   <h4>Steps to Reproduce:</h4>

   <p>The minimal set of steps necessary to trigger the issue. Include any special setup steps.</p>
<pre>
1) View any web page. (I used the default sample page, 
   resource:/res/samples/test0.html)
2) Drag-select the page. (Specifically, while holding down the 
   mouse button, drag the mouse pointer downwards from any point in 
   the browser's content region to the bottom of the browser's 
   content region.)
</pre>

   <h4>Actual Results:</h4>
   What the application did after performing the above steps. 
<pre>
The application crashed. Stack crawl appended below from MacsIssue.
</pre>

   <h4>Expected Results:</h4>

   <p>What the application should have done, were the issue not present.</p>
<pre>
The window should scroll downwards. Scrolled content should 
be selected. (Or, at least, the application should not crash.)
</pre>

   <h4>Build Date &amp; Platform:</h4>

   <p>Date and platform of the build that you first encountered the issue in.</p>
<pre>
11/2/99 build on Mac OS (Checked Viewer &amp; Apprunner)
</pre>

   <h4>Additional Builds and Platforms:</h4>

   <p>Whether or not the issue takes place on other platforms or browsers.</p>
<pre>
- Occurs On
        Seamonkey (11/2/99 build on Windows NT 4.0)

 - Doesn't Occur On
        Seamonkey (11/4/99 build on Red Hat Linux; feature not supported)
        Internet Explorer 5.0 (RTM build on Windows NT 4.0)
        Netscape Communicator 4.5 (RTM build on Mac OS)
</pre>

   <h4>Additional Information:</h4>

   <p>Any other distinguishing information. For crashing issues:</p>

   <ul>
    <li>
     <h4>Win32:</h4>
     if you receive a Dr. Watson error, please note the type of the crash, and the module that the application crashed in. (e.g. access violation in apprunner.exe)
    </li>

    <li>
     <h4>Mac OS:</h4>
     if you're running MacsIssue, please provide the results of a <code>how</code> and an <code>sc</code>.
    </li>

    <li>
     <h4>Unix:</h4>
     please provide a minimized stack trace, which can be generated by typing <code>gdb apprunner core</code> into a shell prompt.
    </li>
   </ul>
<pre>
*** MACSISSUE STACK CRAWL OF CRASH (Mac OS)

Calling chain using A6/R1 links
 Back chain  ISA  Caller
 00000000    PPC  0BA85E74  
 03AEFD80    PPC  0B742248  
 03AEFD30    PPC  0B50FDDC  NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
</pre>

   <p>You're done!</p>

   <p>After double-checking your entries for any possible errors, press the "Commit" button, and your issue report will now be in the IssueZilla database.</p>

   <p>(Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter, and Chris Yeh for contributing to this document. Constructive <a href="mailto:eli@@prometheus-music.com">suggestions</a> welcome.)</p>

   <div class="courtesylinks">
    <p><a href="ProjectIssues.html">Back to Project Issues help</a><br />
    <a href="/servlets/HelpTOC">Back to main Help index</a></p>
   </div>
  </div>
 


@


1.4
log
@extensive markup rework - first pass toward house xhtmlification
@
text
@d1 2
a2 9
<!DOCTYPE html PUBLIC "-//CollabNet//DTD XHTML 1.0 Transitional//EN"
"http://collabnet.com/dtds/collabnet_transitional_10.dtd">
<html>
 <head>
  <title>IssueZilla Issue Writing Guide</title>
<style type="text/css">
 div.c1 {margin-left: 2em}
</style>
 </head>
d4 2
a5 3
 <body>
  <div class="docs" id="docid">
<h2>Issue writing guidelines</h2>
d7 3
a9 1
  <p><strong>Additional resources about issues: Index</strong></p>
d11 2
a12 3
  <div>
   <dl>
    <dt><a href="ProjectIssues.html">Project Issues help</a></dt>
d14 1
a14 1
    <dd><a href="issue_lifecycle.html">The issue life cycle</a></dd>
d16 1
a16 1
    <dd><strong>You are here: Issue writing guidelines</strong></dd>
d18 5
a22 1
    <dd><a href="issuezilla_tipsandtricks.html">IssueZilla tips and tricks</a></dd>
d24 3
a26 1
    <dd><a href="contributing_patches.html">Contributing patches</a></dd>
d28 1
a28 4
    <dt><a href="/servlets/HelpTOC">Back to main Help index</a></dt>
   </dl>
  </div>
  
d30 1
a30 1
  <h3>Why you should read this</h3>
d32 1
a32 4
  <p>Simply put, the more effectively you report an issue, the more likely an engineer will actually fix it.<br />
   <a href="http://IssueZilla.mozilla.org"></a><br />
   These issue writing guidelines are an attempt at a general tutorial on writing effective issue reports for novice issue writers; not every sentence may precisely apply to your software project.</p>
  
d34 1
a34 1
  <h3>How to write a useful issue report</h3>
d36 1
a36 1
  <p>Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:</p>
d38 3
a40 6
  <ol>
   <li>
    <h3>Reproducible.</h3>
   <p>
 If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it "WORKSFORME" or "INVALID", and move on to the next issue. Every detail you can provide helps.
</p>
d42 2
a43 1
   </li>
d45 2
a46 5
   <li>
    <h3>Specific.</h3>
    <p>
The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed.(If a programmer or tester has to decipher an issue, they spend more time cursing the submitter than fixing or testing the problem.)
</p>
d48 3
a50 6
   </li>
  </ol>

  <p>Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up an issue report:</p>

  <h3>BAD:</h3>
d52 1
a52 1
  <p>"My browser crashed. I think I was on foo.com. My computer uses Windows. I think that this is a really bad problem and you should fix it now. By the way, your icons really suck. Nobody will use your software if you keep those ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all messed up. Good luck."
d54 1
a54 1
  </p>
d56 1
a56 1
  <h3>GOOD:</h3>
d58 1
a58 1
  <p>"I crashed each time when I went to foo.com, using the 10.28.99 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced this problem using the 10.28.99 Linux build.</p>
d60 1
a60 1
  <p> It again crashed each time upon drawing the Foo banner at the top of the page. I broke apart the page, and discovered that the following image link will crash the application reproducibly, unless you remove the "border=0" attribute:</p>
d62 1
a62 3
  <p>
 &lt;IMG SRC="http://foo.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News"&gt;"
</p>
d64 1
d66 1
a67 6
   

  <h3>How to Enter your Useful Issue Report into IssueZilla:</h3>
   

  <blockquote>
d70 1
a70 8
   <p>
 Next, be sure that you've reproduced your issue using a recent build. (Engineers tend to be most interested in problems afflicting the code base that they're actively working on, rather than those in a code base that's hundreds of issue fixes obsolete.)
</p>


    <p>
If you've discovered a new issue using a current build, report it in IssueZilla:
</p>
d72 1
a72 1
  </blockquote>
a73 1
  <div>
a82 1
  </div>
a83 1
  <blockquote>
a84 3
   

    
d86 1
a86 6
   <blockquote>
    <h3>Product: In which product did you find the issue?</h3>
  
  <p>
   You just filled this out on the last page.
</p>
d88 1
d90 1
a90 1
     
d92 1
a92 5
    <h3>Version: In which product version did you find the issue?</h3>
  
<p>
     If applicable.
</p>
d94 1
a94 1
     
d96 1
a96 4
    <h3>Component: In which component does the issue exist?</h3>
     <p>
IssueZilla requires that you select a component to enter an issue. (If they all look meaningless, click on the Component link, which links to descriptions of each component, to help you make the best choice.)
</p>
d98 1
a98 1
     
d100 1
a100 5
    <h3>Platform:&#160;On which hardware platform did you find this issue?</h3>
    <p>
(e.g. Macintosh, SGI, Sun, PC.)<br />
     If you know the issue happens on all hardware platforms, choose 'All'. Otherwise, select the platform that you found the issue on, or "Other" if your platform isn't listed.
</p>
d102 1
a102 1
     
d104 1
a104 7
    <h3>OS: On which Operating System (OS) did you find this issue?</h3>
    <p>
(e.g.Linux, Windows NT, Mac OS 8.5.)<br />
     If you know the issue happens on all operating systems, choose 'All'. Otherwise, select the OS that you found the issue on, or "Other" if your OS isn't listed.
</p>

   </blockquote>
d108 1
a108 6
   <blockquote>
    <h3>Issue Type: Is this a defect, enhancement, feature-request, or task?</h3>
    
     <p>
This item defaults to 'defect'. (To determine the most appropriate type of issue, click on the Issue Type link for a full explanation of each choice.)
</p>
d110 1
a110 1
   </blockquote>
d114 3
a116 14
   <blockquote>
    <h3>Assigned To: Which engineer should be responsible for fixing this issue?</h3>
    
    <p>
 IssueZilla will automatically assign the issue to a default engineer upon submitting an issue report; the text box exists to allow you to manually assign it to a different engineer. (To see the list of default engineers for each component, click on the Component link.)
</p>

     

    <h3>Cc: Who else should receive e-mail updates on changes to this issue?</h3>
    
    <p>
 List the full e-mail addresses of other individuals who should receive an e-mail update upon every change to the issue report. You can enter as many e-mail addresses as you'd like; e-mail addresses must be separated by commas, with no spaces between the addresses.
</p>
d118 1
d120 1
a120 1
   </blockquote>
d124 9
a132 36
   <blockquote>
    <h3>URL: On what URL did you discover this issue?</h3>
     <p>
If you encountered the issue on a particular URL, please provide it (or, them) here. If you've isolated the issue to a specific HTML snippet, please also provide a URL for that, too.
</p>
     

    <h3>Summary:</h3>

    <h3>How would you describe the issue, in approximately 60 or fewer characters?</h3>
    
    <p>
 A good summary should <em>quickly and uniquely identify an issue report</em>. Otherwise, developers cannot meaningfully query by issue summary, and will often fail to pay attention to your issue report when reviewing a 10 page issue list.
</p>

<p>
     A summary of "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C" is a useful title. "Software fails" or "install problem" would be examples of a bad title.
</p>


    <h3>Description: What else can you tell the engineer about this issue?</h3>
    <p>
 Please provide as detailed of a problem diagnosis in this field as possible.
</p>

<p>
     Where applicable, using the following issue report template will help ensure that all relevant information comes through:
</p>

     

    <blockquote>
     <h3>Overview Description:</h3>
<p>
     More detailed expansion of summary.
</p>
d134 1
a134 1
      
d136 9
a144 1
     <blockquote>
a147 1
     </blockquote>
d149 1
a149 4
     <h3>Steps to Reproduce:</h3>
<p>
     The minimal set of steps necessary to trigger the issue. Include any special setup steps.
</p>
d151 1
a151 3
      

     <blockquote>
a159 4
     </blockquote>

     <h3>Actual Results:</h3>
     What the application did after performing the above steps.
d161 2
a162 3
      

     <blockquote>
a165 4
     </blockquote>

     <h3>Expected Results:</h3>
     What the application should have done, were the issue not present.
d167 1
a167 1
      
d169 1
a169 1
     <blockquote>
a173 1
     </blockquote>
d175 1
a175 2
     <h3>Build Date &amp; Platform:</h3>
     Date and platform of the build that you first encountered the issue in.
d177 1
a177 3
      

     <blockquote>
a180 4
     </blockquote>

     <h3>Additional Builds and Platforms:</h3>
     Whether or not the issue takes place on other platforms or browsers.
d182 1
a182 1
      
d184 1
a184 1
     <blockquote>
a193 1
     </blockquote>
d195 1
a195 2
     <h3>Additional Information:</h3>
     Any other distinguishing information. For crashing issues:
d197 1
a197 1
      
d199 16
a214 18
     <ul>
      <li>
       <h3>Win32:</h3>
       if you receive a Dr. Watson error, please note the type of the crash, and the module that the application crashed in. (e.g. access violation in apprunner.exe)
      </li>

      <li>
       <h3>Mac OS:</h3>
       if you're running MacsIssue, please provide the results of a <code>how</code> and an <code>sc</code>.
      </li>

      <li>
       <h3>Unix:</h3>
       please provide a minimized stack trace, which can be generated by typing <code>gdb apprunner core</code> into a shell prompt.
      </li>
     </ul>

     <blockquote>
d225 13
a237 17
     </blockquote>
    </blockquote>
   </blockquote>

   <p>You're done!

    After double-checking your entries for any possible errors, press the "Commit" button, and your issue report will now be in the IssueZilla database.<br />
    <i>

   </i> (Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter, and Chris Yeh for contributing to this document. Constructive <a href="mailto:eli@@prometheus-music.com">suggestions</a> welcome.)</p>
  </blockquote>
  <div class="courtesylinks">
  <a href="ProjectIssues.html">Back to Project Issues help</a><br />
 <div class="courtesylinks"><a href="/servlets/HelpTOC">Back to main Help index</a></div>
</div> </div>
</body>
</html>
@


1.3
log
@added index
@
text
@d1 2
d4 6
a9 1
<head>
d11 3
a13 1
<title>IssueZilla Issue Writing Guide</title>
d15 1
a15 2
</head>
<body>
d17 3
a19 13
    <span class="Header" nowrap>Issue writing guidelines</span>  
<p> 
 <span class="PlainText"><strong>Additional resources about issues: Index</strong>
<ul>
	<dl>
	<dt><a href="ProjectIssues.html">Project Issues help</a>
		<dd><a href="issue_lifecycle.html">The issue life cycle</a> 
		<dd><strong>You are here: Issue writing guidelines</strong>
		<dd><a href="issuezilla_tipsandtricks.html"> IssueZilla tips and tricks</a> 
		<dd><a href="contributing_patches.html">Contributing patches</a>
	<dt><a href="/servlets/HelpTOC">Back to main Help index</a>
	</dl>
</ul>
d21 1
d23 143
a165 1
 
d167 4
a170 2
 <hr noshade size=1>
     <span class="InputHeader">Why you should read this</span>
d172 1
a172 7
   <span class="PlainText">
     <p>Simply put, the more effectively you report an issue, the more
     likely an engineer will actually fix it. <br> 
     <a href="http://IssueZilla.mozilla.org"></a><br> These issue writing
     guidelines are an attempt at a general tutorial on writing
     effective issue reports for novice issue writers; not every
     sentence may precisely apply to your software project.
d174 22
d197 21
a217 64
 <hr noshade size=1>
     <span class="InputHeader">How to write a useful issue report</span>
     <p>Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:
     <ol>

      <li><span class=inputheader>Reproducible.</span> If an engineer
      can't see it or conclusively prove that it exists, the engineer
      will probably stamp it &quot;WORKSFORME&quot; or
      &quot;INVALID&quot;, and move on to the next issue. Every detail
      you can provide helps. <p>

      <li><span class=inputheader>Specific.</span> The quicker the
      engineer can isolate the issue to a specific problem, the more
      likely it'll be expediently fixed.(If a programmer or tester has
      to decipher an issue, they spend more time cursing the submitter
      than fixing or testing the problem.)

     </ol>

     <p>Let's say the application you're testing is a web browser. You
     crash at foo.com, and want to write up an issue report:


     <p><span class="InputHeader">BAD:</span> &quot;My browser
     crashed. I think I was on foo.com. My computer uses Windows. I
     think that this is a really bad problem and you should fix it
     now. By the way, your icons really suck. Nobody will use your
     software if you keep those ugly icons. Oh, and my grandmother's
     home page doesn't look right, either, it's all messed up. Good
     luck.&quot;

<br>
<br>

     <span class="InputHeader">GOOD: </span>&quot;I crashed each time
     when I went to foo.com, using the 10.28.99 build on a Win NT 4.0
     (Service Pack 5) system. I also rebooted into Linux, and
     reproduced this problem using the 10.28.99 Linux build.<br><br>
     It again crashed each time upon drawing the Foo banner at the top
     of the page. I broke apart the page, and discovered that the
     following image link will crash the application reproducibly,
     unless you remove the &quot;border=0&quot; attribute:
     <br>
     <br>
     &lt;IMG
     SRC=&quot;http://foo.com/images/topics/topicfoos.gif&quot;
     width=34 height=44 border=0 alt=&quot;News&quot;&gt;&quot;

<br>
<br>

     <p><span class=inputheader>How to Enter your Useful Issue Report into IssueZilla:</span>


<blockquote>
    <p>Before you enter your issue, use the IssueZilla Query Page to determine whether the
defect you've discovered is a known issue, and has already been reported. (If your
issue is the 37th duplicate of a known issue, you're more likely to annoy the engineer.
Annoyed engineers fix fewer issues.)<br><br>
Next, be sure that you've reproduced your issue using a recent build. (Engineers tend
to be most interested in problems afflicting the code base that they're actively
working on, rather than those in a code base that's hundreds of issue fixes obsolete.)<br><br>
If you've discovered a new issue using a current build, report it in IssueZilla:
</blockquote>
d219 3
d223 1
a223 2
     <ol>
      <ol>
d225 5
a229 1
      <li>From your IssueZilla main page, choose &quot;Enter a new issue&quot;.
d231 1
a231 92
      <li>Select the product that you've found an issue in.

      <li>Enter your e-mail address, password, and press the
      &quot;Login&quot; button.  (If you don't yet have a password,
      leave the password text box empty, and press the &quot;E-mail me
      a password&quot; button instead. You'll receive an E-mail
      message with your password shortly.)

     </ol>
    <p>Now, fill out the form. Here's what it all means:
     </ol>



<blockquote>
    <p><span class=inputheader>Where did you find the issue?</span>

<blockquote>
    <p><span class="InputHeader">Product: In which product did you find the issue?</span><br>
You just filled this out on the last page.</p>
    <p><span class="InputHeader">Version: In which product version did you find the issue?</span><br>
If applicable.
    <p><span class="InputHeader">Component: In which component does the issue exist?</span><br>
IssueZilla requires that you select a component to enter an issue. (If they all look meaningless,
click on the Component link, which links to descriptions of each component, to help
you make the best choice.)</p>
    <p><span class="InputHeader">Platform:&#160;On which hardware platform did you find this issue?</span>
(e.g. Macintosh, SGI, Sun, PC.)<br>
If you know the issue happens on all hardware platforms, choose 'All'. Otherwise, select
the platform that you found the issue on, or &quot;Other&quot; if your platform isn't
listed.</p>
    <p><span class="InputHeader">OS: On which Operating System (OS) did you find this issue?</span> (e.g.Linux, Windows NT, Mac OS 8.5.)<br>
If you know the issue happens on all operating systems, choose 'All'. Otherwise, select the OS that
you found the issue on, or &quot;Other&quot; if your OS isn't listed.</p>
</blockquote>
    <p><span class="InputHeader"><br>How important is the issue?</span>
<blockquote>
    <p><span class="InputHeader">Issue Type: Is this a defect, enhancement,
feature-request, or task?</span><br> This item defaults to
'defect'. (To determine the most appropriate type of issue,
click on the Issue Type link for a full explanation of each
choice.)
</blockquote>
    <p><span class="InputHeader"><br>Who will be following up on the issue?</span>
<blockquote>
    <p><span class="InputHeader">Assigned To: Which engineer should be responsible for fixing this issue?</span><br>
IssueZilla will automatically assign the issue to a default engineer upon submitting
an issue report; the text box exists to allow you to manually assign it to a different
engineer. (To see the list of default engineers for each component, click on the
Component link.)</p>
    <p><span class="InputHeader">Cc: Who else should receive e-mail updates on changes to this issue? </span><br>
List the full e-mail addresses of other individuals who should receive an e-mail
update upon every change to the issue report. You can enter as many e-mail addresses
as you'd like; e-mail addresses must be separated by commas, with no spaces between
the addresses.
</blockquote>
    <p><span class="InputHeader"><br>What else can you tell the engineer about the issue?</span></p>
<blockquote>
    <p><span class="InputHeader">URL: On what URL did you discover this issue?</span><br>
If you encountered the issue on a particular URL, please provide it (or, them) here.
If you've isolated the issue to a specific HTML snippet, please also provide a URL
for that, too.

    <p><span class="InputHeader">Summary:</span> <span
    class="InputHeader">How would you describe the issue, in
    approximately 60 or fewer characters?</span><br> A good summary
    should <u>quickly and uniquely identify an issue
    report</u>. Otherwise, developers cannot meaningfully query by
    issue summary, and will often fail to pay attention to your issue
    report when reviewing a 10 page issue list.<br><br> A summary of
    &quot;PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C&quot; is
    a useful title. &quot;Software fails&quot; or &quot;install
    problem&quot; would be examples of a bad title.

    <p><br>

     <span class="InputHeader">Description: What else can you tell the engineer about this issue? </span><br>
Please provide as detailed of a problem diagnosis in this field as possible. <br>
<br>
Where applicable, using the following issue report template will help ensure that all
relevant information comes through:


		<blockquote>
			<p><span class=inputheader>Overview Description:</span> More detailed expansion of summary.

			<blockquote>
				<pre><font size="2">Drag-selecting any page crashes Mac builds in NSGetFactory</font></pre>

			</blockquote>
			<p><span class=inputheader>Steps to Reproduce: </span>The minimal set of steps necessary to trigger the issue.
			Include any special setup steps. 
d233 16
a248 2
			<blockquote>
				<pre><font size="2">1) View any web page. (I used the default sample page, 
d253 17
a269 1
   content region.)</font></pre>
d271 1
a271 2
			</blockquote>
			<p><span class=inputheader>Actual Results:</span> What the application did after performing the above steps.
d273 6
a278 2
			<blockquote>
				<pre><font size="2">The application crashed. Stack crawl appended below from MacsIssue.</font></pre>
d280 2
a281 3
			</blockquote>
			<p><span class=inputheader>Expected Results:</span> What the application should have done, were the issue not
			present.
d283 1
a283 3
			<blockquote>
				<pre><font size="2">The window should scroll downwards. Scrolled content should 
be selected. (Or, at least, the application should not crash.)</font></pre>
d285 5
a289 3
			</blockquote>
			<p><span class=inputheader>Build Date &amp; Platform:</span> Date and platform of the build that you first
			encountered the issue in.
d291 2
a292 2
			<blockquote>
				<pre><font size="2">11/2/99 build on Mac OS (Checked Viewer &amp; Apprunner)</font></pre>
d294 1
a294 3
			</blockquote>
			<p><span class=inputheader>Additional Builds and Platforms:</span> Whether or not the issue takes place on
			other platforms or browsers.
d296 3
a298 2
			<blockquote>
				<pre><font size="2"> - Occurs On
d304 1
a304 1
        Netscape Communicator 4.5 (RTM build on Mac OS)</font>
d306 4
d311 1
a311 2
			</blockquote>
			<p><span class=inputheader>Additional Information:</span> Any other distinguishing information. For crashing issues:
d313 20
a332 14
			<ul>
	<li><span class=inputheader>Win32:</span> if you receive a Dr. Watson error, please note the type of the
	crash, and the module that the application crashed in. (e.g. access violation in
	apprunner.exe)
	<li><span class=inputheader>Mac OS:</span> if you're running MacsIssue, please provide the results of a <span class=inputheader><tt>how</tt></span>
	and an <span class=inputheader><tt>sc</tt></span>.
	<li><span class=inputheader>Unix: </span>please provide a minimized stack trace, which can be generated by
	typing <span class=inputheader><tt>gdb apprunner core</tt></span> into a shell prompt.
			</ul>


			<blockquote>
				<p>
				<pre><font size="2">*** MACSISSUE STACK CRAWL OF CRASH (Mac OS)
d339 19
a357 5
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0</font></pre>

			</blockquote>

		</blockquote>
a358 15
	</blockquote>
	<p>You're done! <br>
	<br>
	After double-checking your entries for any possible errors, press the &quot;Commit&quot;
	button, and your issue report will now be in the IssueZilla database.<br>
	<i><br>
	<br>
	</i><font size="2">(Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter,
	and Chris Yeh for contributing to this document. Constructive </font><a href="mailto:eli@@prometheus-music.com"><font
	size="2">suggestions</font></a><font size="2"> welcome.)</font>
	</blockquote>

 <hr noshade size=1>
<a href="ProjectIssues.html">Back to Project Issues help</a><br>
<a href="/servlets/HelpTOC">Back to main Help index</a>
a359 2
</body>
</html>
@


1.2
log
@added <title> tags to all files
@
text
@d1 2
a2 2
<HTML>
<HEAD>
d4 1
a4 1
<TITLE>Issuezilla Issue Writing Guide</TITLE>
d6 2
a7 2
</HEAD>
<BODY>
d9 24
a32 14
<TABLE BORDER="0" CELLSPACING="1" CELLPADDING="3" BORDER="0" WIDTH="100%">
  <TR>
    <TD class="Header" nowrap>Issue writing guidelines</TD>  
  </TR>
</TABLE>
<TABLE BORDER="0" CELLSPACING="2" CELLPADDING="2" BORDER="0" width="100%">
  <TR>
    <TD class="PlainText">
     <P>
     <SPAN class=InputHeader>Why you should read this</span>

     <P>Simply put, the more effectively you report an issue, the more
     likely an engineer will actually fix it. <BR> 
     <A HREF="http://IssueZilla.mozilla.org"></A><BR> These issue writing
d37 5
a41 4
     <P>
     <SPAN class=InputHeader>How to write a useful issue report</span>
     <P>Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:
     <OL>
d43 1
a43 1
      <LI><SPAN class=InputHeader>Reproducible.</span> If an engineer
d49 1
a49 1
      <LI><SPAN class=InputHeader>Specific.</span> The quicker the
d52 1
a52 1
      to decypher an issue, they spend more time cursing the submitter
d55 1
a55 1
     </OL>
d57 1
a57 1
     <P>Let's say the application you're testing is a web browser. You
d61 1
a61 1
     <P><span class="InputHeader">BAD:</span> &quot;My browser
d66 1
a66 1
     home page doesn't look right, either, it's allmessed up. Good
d69 2
a70 2
<BR>
<BR>
d75 1
a75 1
     reproduced this problem using the 10.28.99 Linux build.<BR><BR>
d80 2
a81 2
     <BR>
     <BR>
d86 2
a87 2
<BR>
<BR>
d89 1
a89 1
     <P><span class=InputHeader>How to Enter your Useful Issue Report into IssueZilla:</span>
d92 2
a93 2
<BLOCKQUOTE>
    <P>Before you enter your issue, use the IssueZilla Query Page to determine whether the
d96 1
a96 1
Annoyed engineers fix fewer issues.)<BR><BR>
d99 1
a99 1
working on, rather than those in a code base that's hundreds of issue fixes obsolete.)<BR><BR>
d101 1
a101 1
</BLOCKQUOTE>
d104 2
a105 2
     <OL>
      <OL>
d107 1
a107 1
      <LI>From your IssueZilla main page, choose &quot;Enter a new issue&quot;.
d109 1
a109 1
      <LI>Select the product that you've found an issue in.
d111 1
a111 1
      <LI>Enter your e-mail address, password, and press the
d117 3
a119 3
     </OL>
    <P>Now, fill out the form. Here's what it all means:
     </OL>
d123 2
a124 2
<BLOCKQUOTE>
    <P><SPAN class=InputHeader>Where did you find the issue?</span>
d126 4
a129 4
<BLOCKQUOTE>
    <P><span class="InputHeader">Product: In which product did you find the issue?</span><BR>
You just filled this out on the last page.</P>
    <P><span class="InputHeader">Version: In which product version did you find the issue?</span><BR>
d131 1
a131 1
    <P><span class="InputHeader">Component: In which component does the issue exist?</span><BR>
d134 3
a136 3
you make the best choice.)</P>
    <P><span class="InputHeader">Platform:&#160;On which hardware platform did you find this issue?</span>
(e.g. Macintosh, SGI, Sun, PC.)<BR>
d139 9
a147 9
listed.</P>
    <P><span class="InputHeader">OS: On which Operating System (OS) did you find this issue?</span> (e.g.Linux, Windows NT, Mac OS 8.5.)<BR>
If you know the issue happens on all OSs, choose 'All'. Otherwise, select the OS that
you found the issue on, or &quot;Other&quot; if your OS isn't listed.</P>
</BLOCKQUOTE>
    <P><span class="InputHeader"><BR>How important is the issue?</span>
<BLOCKQUOTE>
    <P><span class="InputHeader">Issue Type: Is this a defect, enhancement,
feature-request, or task?</span><BR> This item defaults to
d151 4
a154 4
</BLOCKQUOTE>
    <P><span class="InputHeader"><BR>Who will be following up on the issue?</span>
<BLOCKQUOTE>
    <P><span class="InputHeader">Assigned To: Which engineer should be responsible for fixing this issue?</span><BR>
d158 2
a159 2
Component link.)</P>
    <P><span class="InputHeader">Cc: Who else should receive e-mail updates on changes to this issue? </span><BR>
d164 4
a167 4
</BLOCKQUOTE>
    <P><span class="InputHeader"><BR>What else can you tell the engineer about the issue?</span></P>
<BLOCKQUOTE>
    <P><span class="InputHeader">URL: On what URL did you discover this issue?</span><BR>
d172 1
a172 1
    <P><span class="InputHeader">Summary:</span> <span
d174 3
a176 3
    approximately 60 or fewer characters?</span><BR> A good summary
    should <U>quickly and uniquely identify an issue
    report</U>. Otherwise, developers cannot meaningfully query by
d178 1
a178 1
    report when reviewing a 10 page issue list.<BR><BR> A summary of
d183 1
a183 1
    <P><BR>
d185 3
a187 3
     <span class="InputHeader">Description: What else can you tell the engineer about this issue? </span><BR>
Please provide as detailed of a problem diagnosis in this field as possible. <BR>
<BR>
d192 2
a193 2
		<BLOCKQUOTE>
			<P><span class=InputHeader>Overview Description:</span> More detailed expansion of summary.
d195 2
a196 2
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2">Drag-selecting any page crashes Mac builds in NSGetFactory</FONT></PRE>
d198 2
a199 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Steps to Reproduce: </span>The minimal set of steps necessary to trigger the issue.
d202 2
a203 2
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2">1) View any web page. (I used the default sample page, 
d208 1
a208 1
   content region.)</FONT></PRE>
d210 2
a211 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Actual Results:</span> What the application did after performing the above steps.
d213 2
a214 2
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2">The application crashed. Stack crawl appended below from MacsIssue.</FONT></PRE>
d216 2
a217 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Expected Results:</span> What the application should have done, were the issue not
d220 3
a222 3
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2">The window should scroll downwards. Scrolled content should 
be selected. (Or, at least, the application should not crash.)</FONT></PRE>
d224 2
a225 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Build Date &amp; Platform:</span> Date and platform of the build that you first
d228 2
a229 2
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2">11/2/99 build on Mac OS (Checked Viewer &amp; Apprunner)</FONT></PRE>
d231 2
a232 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Additional Builds and Platforms:</span> Whether or not the issue takes place on
d235 2
a236 2
			<BLOCKQUOTE>
				<PRE><FONT SIZE="2"> - Occurs On
d242 2
a243 2
        Netscape Communicator 4.5 (RTM build on Mac OS)</FONT>
</PRE>
d245 2
a246 2
			</BLOCKQUOTE>
			<P><span class=InputHeader>Additional Information:</span> Any other deissueging information. For crashing issues:
d248 2
a249 2
			<UL>
	<LI><span class=InputHeader>Win32:</span> if you receive a Dr. Watson error, please note the type of the
d252 5
a256 5
	<LI><span class=InputHeader>Mac OS:</span> if you're running MacsIssue, please provide the results of a <span class=InputHeader><TT>how</TT></span>
	and an <span class=InputHeader><TT>sc</TT></span>.
	<LI><span class=InputHeader>Unix: </span>please provide a minimized stack trace, which can be generated by
	typing <span class=InputHeader><TT>gdb apprunner core</TT></span> into a shell prompt.
			</UL>
d259 3
a261 3
			<BLOCKQUOTE>
				<P>
				<PRE><FONT SIZE="2">*** MACSISSUE STACK CRAWL OF CRASH (Mac OS)
d268 1
a268 1
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0</FONT></PRE>
d270 1
a270 1
			</BLOCKQUOTE>
d272 1
a272 1
		</BLOCKQUOTE>
d274 3
a276 3
	</BLOCKQUOTE>
	<P>You're done! <BR>
	<BR>
d278 11
a288 7
	button, and your issue report will now be in the IssueZilla database.<BR>
	<I><BR>
	<BR>
	</I><FONT SIZE="2">(Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter,
	and Chris Yeh for contributing to this document. Constructive </FONT><A HREF="mailto:eli@@prometheus-music.com"><FONT
	SIZE="2">suggestions</FONT></A><FONT SIZE="2"> welcome.)</FONT>
	</BLOCKQUOTE>
d290 2
a291 12


    </TD>
  </TR>
</TABLE>

</BODY>

</HTML>

</BODY>
</HTML>
@


1.1
log
@moved core documentation into helm, fewer overrides need to be in instances now
@
text
@d1 7
d285 2
@


1.1.1.1
log
@Replacing the HEAD with the HELM_PEER_PORT_BRANCH.
@
text
@a0 7
<HTML>
<HEAD>

<TITLE>Issuezilla Issue Writing Guide</TITLE>

</HEAD>
<BODY>
a277 2
</BODY>
</HTML>
@


1.1.8.1
log
@porting changes from the head to the branch
@
text
@a0 7
<HTML>
<HEAD>

<TITLE>Issuezilla Issue Writing Guide</TITLE>

</HEAD>
<BODY>
a277 2
</BODY>
</HTML>
@


1.1.4.1
log
@adding the generic, default docs into this branch, bc they are in the head and nec for instantiations using stable branches
@
text
@@

