content/qa/issue_handling/basic_rules.html - openoffice-org - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <meta http-equiv="content-type"
  content="text/html; charset=ISO-8859-1">
   <title>Basic IssueTracker rules</title>
 </head>
 <body>
 <div class="app">
 <h1>Basic Bugzilla rules</h1>
 <h3>Why you should read this</h3>
 <p> Imagine how many people later on will read your issue (means the
 issue which you submitted, or which you participated in) </p>
 <ul>
   <li> community members who performe triage on defects</li>
   <li> developers who finally fix the defect </li>
   <li> sometimes developers who need to do preliminary work</li>
   <li> QA engineer(s) who needs to verify the fix</li>
   <li> everybody who has the same problem and tries to understand
 whether </li>
   <ul>
     <li> <span style="font-style: italic;">your</span> defect also
 describes <span style="font-style: italic;">his/her</span> problem.</li>
     <li> or whether your issue is one they like to vote for</li>
   </ul>
   <li> possibly a user experience team member evaluating a feature
 request</li>
   <li> possibly a release team member evaluating whether the defect is
 important enough to be included in some maintenance update such as
 1.1.1.</li>
 </ul>
 You see, there are a lot of&nbsp; people who may read what you wrote.
 Thus, the majority of the rules below focuses on making <span
  style="font-style: italic;">reading</span> easier: Though they
 sometimes take you some little time to follow, they often save others a
 <span style="font-style: italic;">lot</span> of time later on.
 <p> So please, not only when you submit new issues, but also when you
 add comments to existing issues, try to help others by obeying these
 simple rules.<br/>
 Since not obeying them makes defect handling more difficult (sometimes <span
  style="font-style: italic;">much</span> more difficult), people may
 tend to not deal with your issues until they are in a shape to
 reasonably do so. </p>
 <h3>The rules</h3>
 <p> For those of you who like it short and simple: </p>
 <ul>
   <li style="font-weight: bold;"> <a href="#one_per_issue">One problem - One issue</a></li>
   <li style="font-weight: bold;"> <a href="#summary">Provide a meaningful summary</a></li>
   <li style="font-weight: bold;"> <a href="#reproducibility">Provide step-by-step descriptions</a></li>
   <li style="font-weight: bold;"> <a href="#bugdoc">Provide sample documents, if possible</a></li>
   <li style="font-weight: bold;"> <a href="#attachments">Use Attachments where possible</a></li>
   <li style="font-weight: bold;"> <a href="#complete">Put all relevant information into the issue</a></li>

 </ul>
 <h4><a name="one_per_issue"></a>One problem - One issue</h4>
 <p> When you report a problem, please submit <span
  style="text-decoration: underline;">one issue per problem</span>.
 There are various reasons for this, amongst them: </p>
 <ul>
   <li> The more crowded an issue is, the more likely is it that some
 problems may get lost over time.</li>
   <li> Different problems are most likely to be handled by different
 people (both in engineering, where the problem is fixed, and in QA,
 where it's verified). The more problems you put into the issue, the
 more difficult is this issue to handle for all involved parties.</li>
 </ul>
 In particular, if you're going to write sentences like "Besides this, I
 noticed that ...." or "There are several problems with....", then
 please seriously ask yourself whether you should submit multiple issues
 instead of a single one.<br/>
 If you don't follow this rule, be prepared for people asking you to
 split up your issue.
 <h4><a name="summary"></a>Provide a meaningful summary</h4>
 <p> A lot of people have to deal with a high number of issues on a
 regular basis. Usually, this happens with generating reports about
 issues, where the summary of all issues, plus some additional data, is
 displayed. Thus, the summary of an issue is of very high importance: If
 properly chosen, it allows to<br/>
 </p>
 <ul>
   <li> easily <span style="text-decoration: underline;">recognize</span>
 an issue in a list of dozens of others</li>
   <li> <span style="text-decoration: underline;">find</span> an issue.
 Since duplicate issues are draining a lot of work from engaged
 community members, we always ask people to look whether the problem,
 which they are going to submit as issue, is already known and reported.
 Of course this works best if the summaries of the existing issues are
 as descriptive as possible.</li>
   <li> <span style="text-decoration: underline;">judge the importance</span>
 of an issue. "Spreadsheet problem" is less likely to be handled
 appropriately than "Spreadsheet: Data loss when ...." or "Label X in
 dialog Y has a wrong offset (2 pixels)"</li>
 </ul>
 Thus, please avoid summaries like "Big Bug in OpenOffice" or
 "Impress problem" - they are of no real help, and force people to waste
 time to actually browse to the issue (instead of seeing it in a report)
 to see what it is about.<br/>
 <h4><a name="reproducibility"></a>Provide step-by-step descriptions</h4>
 <p> You, as the submitter of a problem, know exactly what you were
 doing when you were hit by the problem. However, most other people
 probably don't. For instance, they may have a completely different
 workflow for doing the same things you are doing. </p>
 <p> Even an phrasing as innocent as "format the text as bold" bears the
 potential for a misunderstanding: You can get a bold text by assigning
 a style to it, by selecting it and pressing the respective button in
 the toolbox, by choosing "<span style="font-family: monospace;">Style|Bold</span>"
 from the context menu, by choosing "<span
  style="font-family: monospace;">Format|Character</span>" from the menu
 or "<span style="font-family: monospace;">Character</span>" from the
 context menu and then doing the change in the dialog. Thus, a problem
 description such as "When I try to format the text as bold
 OpenOffice.org crashes" is of nearly no use, since it <span
  style="font-style: italic;">forces</span> other people to ask back
 what you meant. </p>
 <p> This may be a trivial example, and you could argue that other
 people can simply try, and then they will eventually encounter the
 problem and thus know what you meant. But, there are reasons against
 this:<br/>
 </p>
 <ul>
   <li> Though the problem may seem simple to you, there may be deeper
 reasons which prevent others from trying. For instance, it may crash
 only if you customized the "<span style="font-family: monospace;">Bold</span>"
 icon into a non-standard toolbox. In such a case, people will try for
 no avail, without encountering your problem at all, and thus waste time.<br/>
   </li>
   <li> Writing down <span style="font-style: italic;">exactly</span>
 what you did costs you some time <span style="font-style: italic;">once</span>,
 but <span style="font-style: italic;">every</span> reader (there may
 be numerous during the lifetime of an issue!) needs time for guessing
 and trying. It's more efficient if you do it, and QA and engineering
 can concentrate on fixing the problem, instead of performing triage on it.</li>
   <li> There are a lot of scenarios where the set of possibility is
 much larger. Formatting a text as bold may be simple and easy (though
 you've already seen that there are at least 5 ways to do so), but other
 tasks may require more steps which <span style="font-style: italic;">you</span>
 implicitly know, but <span style="font-style: italic;">your reader</span>
 doesn't.</li>
 </ul>
 You may be tempted to consider it stupid to write a description like<br/>
 <ul>
   <li> open a new writer document</li>
   <li> enter some arbitrary text</li>
   <li> select the whole text via "<span style="font-family: monospace;">Edit|Select
 all</span>"</li>
   <li> from the context menu of the text, chose "<span
  style="font-family: monospace;">Style|Bold</span>"</li>
   <li> =&gt; OpenOffice crashes</li>
 </ul>
 Indeed there may be cases where this level of detail is
 superfluous. But believe us, more often than not, it in the final
 consequences saves more time than it takes.
 <p> Please always be aware that often enough, the reader of your issue
 description does not have the same background, with respect to the
 particular task you're doing, that you yourself have. </p>
 <h4><a name="bugdoc"></a>Provide sample documents, if possible</h4>
 <p> If there is a problem with a particular document, then attach it.
 This most often allows people to really easily reproduce your problem
 by simply opening the attached document.<br/>
 </p>
 <p> If the description how to reproduce a defect (see <a
  href="#reproducibility">Provide step-by-step descriptions</a>) exceeds
 a certain limit, ask yourself whether you can submit the <span
  style="font-style: italic;">result</span> of the description as sample
 document, and attach it to the issue.<br/>
 </p>
 <p> Oh, and one thing: If there is a problem on page 3 of your
 1000-page diploma thesis, then please first try if the problem also
 occurs if you strip all pages except the third one. If so, then please
 simply attach the stripped version of the document, not all 1000 pages
 .... </p>

 <h4><a name="attachments"></a>Use attachments where possible</h4>
 <p> Don't paste large files into the description. For instance, if
 you're asked to provide a stack of a crash, copy this stack into a
 file, then <span style="text-decoration: underline;">attach</span>
 this file. If you have some Basic macro or Java code which triggers a
 problem, copy it into a separate file, and <span
  style="text-decoration: underline;">attach</span> this file. </p>
 <p> The reason here is simple: A 3-pager within the description of an
 issue makes reading the issue really difficult. Everybody who wants to
 get an impression of the issue needs to scan through a lot of
 information which, though definitely important, is of only peripheral
 interest for them at the moment. </p>

 <h4><a name="complete"></a>Put all relevant information into the issue</h4>
 <p>Don't use (only) links to refer to the bug descriptions. Links tend to become outdated
 over time, so if half a year later, somebody looks at your issue, it has become meaningless.
 </p>

 <p>If there is some external resource describing your problem - fine, link it! But don't rely
 on links as the <em>only</em> mean for bug descriptions - copy the information which is
 necessary to reproduce the problem into the issue.</p>

 <hr/>
 The author of the original document is <a
  href="mailto:fs@openoffice.org">Frank Sch&ouml;nheit</a>. Constructive
 <a href="mailto:fs@openoffice.org">feedback is welcome</a>. You may
 also consider visiting <a href="mailto:qa@openoffice.apache.org"> the
 mailing list</a> dedicated to discussing issue handling.
 <hr/>
 <div> </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="content-type"
	content="text/html; charset=ISO-8859-1">
	<title>Basic IssueTracker rules</title>
	</head>
	<body>
	<div class="app">
	<h1>Basic Bugzilla rules</h1>
	<h3>Why you should read this</h3>
	<p> Imagine how many people later on will read your issue (means the
	issue which you submitted, or which you participated in) </p>
	<ul>
	<li> community members who performe triage on defects</li>
	<li> developers who finally fix the defect </li>
	<li> sometimes developers who need to do preliminary work</li>
	<li> QA engineer(s) who needs to verify the fix</li>
	<li> everybody who has the same problem and tries to understand
	whether </li>
	<ul>
	<li> <span style="font-style: italic;">your</span> defect also
	describes <span style="font-style: italic;">his/her</span> problem.</li>
	<li> or whether your issue is one they like to vote for</li>
	</ul>
	<li> possibly a user experience team member evaluating a feature
	request</li>
	<li> possibly a release team member evaluating whether the defect is
	important enough to be included in some maintenance update such as
	1.1.1.</li>
	</ul>
	You see, there are a lot of  people who may read what you wrote.
	Thus, the majority of the rules below focuses on making <span
	style="font-style: italic;">reading</span> easier: Though they
	sometimes take you some little time to follow, they often save others a
	<span style="font-style: italic;">lot</span> of time later on.
	<p> So please, not only when you submit new issues, but also when you
	add comments to existing issues, try to help others by obeying these
	simple rules.<br/>
	Since not obeying them makes defect handling more difficult (sometimes <span
	style="font-style: italic;">much</span> more difficult), people may
	tend to not deal with your issues until they are in a shape to
	reasonably do so. </p>
	<h3>The rules</h3>
	<p> For those of you who like it short and simple: </p>
	<ul>
	<li style="font-weight: bold;"> <a href="#one_per_issue">One problem - One issue</a></li>
	<li style="font-weight: bold;"> <a href="#summary">Provide a meaningful summary</a></li>
	<li style="font-weight: bold;"> <a href="#reproducibility">Provide step-by-step descriptions</a></li>
	<li style="font-weight: bold;"> <a href="#bugdoc">Provide sample documents, if possible</a></li>
	<li style="font-weight: bold;"> <a href="#attachments">Use Attachments where possible</a></li>
	<li style="font-weight: bold;"> <a href="#complete">Put all relevant information into the issue</a></li>

	</ul>
	<h4><a name="one_per_issue"></a>One problem - One issue</h4>
	<p> When you report a problem, please submit <span
	style="text-decoration: underline;">one issue per problem</span>.
	There are various reasons for this, amongst them: </p>
	<ul>
	<li> The more crowded an issue is, the more likely is it that some
	problems may get lost over time.</li>
	<li> Different problems are most likely to be handled by different
	people (both in engineering, where the problem is fixed, and in QA,
	where it's verified). The more problems you put into the issue, the
	more difficult is this issue to handle for all involved parties.</li>
	</ul>
	In particular, if you're going to write sentences like "Besides this, I
	noticed that ...." or "There are several problems with....", then
	please seriously ask yourself whether you should submit multiple issues
	instead of a single one.<br/>
	If you don't follow this rule, be prepared for people asking you to
	split up your issue.
	<h4><a name="summary"></a>Provide a meaningful summary</h4>
	<p> A lot of people have to deal with a high number of issues on a
	regular basis. Usually, this happens with generating reports about
	issues, where the summary of all issues, plus some additional data, is
	displayed. Thus, the summary of an issue is of very high importance: If
	properly chosen, it allows to<br/>
	</p>
	<ul>
	<li> easily <span style="text-decoration: underline;">recognize</span>
	an issue in a list of dozens of others</li>
	<li> <span style="text-decoration: underline;">find</span> an issue.
	Since duplicate issues are draining a lot of work from engaged
	community members, we always ask people to look whether the problem,
	which they are going to submit as issue, is already known and reported.
	Of course this works best if the summaries of the existing issues are
	as descriptive as possible.</li>
	<li> <span style="text-decoration: underline;">judge the importance</span>
	of an issue. "Spreadsheet problem" is less likely to be handled
	appropriately than "Spreadsheet: Data loss when ...." or "Label X in
	dialog Y has a wrong offset (2 pixels)"</li>
	</ul>
	Thus, please avoid summaries like "Big Bug in OpenOffice" or
	"Impress problem" - they are of no real help, and force people to waste
	time to actually browse to the issue (instead of seeing it in a report)
	to see what it is about.<br/>
	<h4><a name="reproducibility"></a>Provide step-by-step descriptions</h4>
	<p> You, as the submitter of a problem, know exactly what you were
	doing when you were hit by the problem. However, most other people
	probably don't. For instance, they may have a completely different
	workflow for doing the same things you are doing. </p>
	<p> Even an phrasing as innocent as "format the text as bold" bears the
	potential for a misunderstanding: You can get a bold text by assigning
	a style to it, by selecting it and pressing the respective button in
	the toolbox, by choosing "<span style="font-family: monospace;">Style\|Bold</span>"
	from the context menu, by choosing "<span
	style="font-family: monospace;">Format\|Character</span>" from the menu
	or "<span style="font-family: monospace;">Character</span>" from the
	context menu and then doing the change in the dialog. Thus, a problem
	description such as "When I try to format the text as bold
	OpenOffice.org crashes" is of nearly no use, since it <span
	style="font-style: italic;">forces</span> other people to ask back
	what you meant. </p>
	<p> This may be a trivial example, and you could argue that other
	people can simply try, and then they will eventually encounter the
	problem and thus know what you meant. But, there are reasons against
	this:<br/>
	</p>
	<ul>
	<li> Though the problem may seem simple to you, there may be deeper
	reasons which prevent others from trying. For instance, it may crash
	only if you customized the "<span style="font-family: monospace;">Bold</span>"
	icon into a non-standard toolbox. In such a case, people will try for
	no avail, without encountering your problem at all, and thus waste time.<br/>
	</li>
	<li> Writing down <span style="font-style: italic;">exactly</span>
	what you did costs you some time <span style="font-style: italic;">once</span>,
	but <span style="font-style: italic;">every</span> reader (there may
	be numerous during the lifetime of an issue!) needs time for guessing
	and trying. It's more efficient if you do it, and QA and engineering
	can concentrate on fixing the problem, instead of performing triage on it.</li>
	<li> There are a lot of scenarios where the set of possibility is
	much larger. Formatting a text as bold may be simple and easy (though
	you've already seen that there are at least 5 ways to do so), but other
	tasks may require more steps which <span style="font-style: italic;">you</span>
	implicitly know, but <span style="font-style: italic;">your reader</span>
	doesn't.</li>
	</ul>
	You may be tempted to consider it stupid to write a description like<br/>
	<ul>
	<li> open a new writer document</li>
	<li> enter some arbitrary text</li>
	<li> select the whole text via "<span style="font-family: monospace;">Edit\|Select
	all</span>"</li>
	<li> from the context menu of the text, chose "<span
	style="font-family: monospace;">Style\|Bold</span>"</li>
	<li> => OpenOffice crashes</li>
	</ul>
	Indeed there may be cases where this level of detail is
	superfluous. But believe us, more often than not, it in the final
	consequences saves more time than it takes.
	<p> Please always be aware that often enough, the reader of your issue
	description does not have the same background, with respect to the
	particular task you're doing, that you yourself have. </p>
	<h4><a name="bugdoc"></a>Provide sample documents, if possible</h4>
	<p> If there is a problem with a particular document, then attach it.
	This most often allows people to really easily reproduce your problem
	by simply opening the attached document.<br/>
	</p>
	<p> If the description how to reproduce a defect (see <a
	href="#reproducibility">Provide step-by-step descriptions</a>) exceeds
	a certain limit, ask yourself whether you can submit the <span
	style="font-style: italic;">result</span> of the description as sample
	document, and attach it to the issue.<br/>
	</p>
	<p> Oh, and one thing: If there is a problem on page 3 of your
	1000-page diploma thesis, then please first try if the problem also
	occurs if you strip all pages except the third one. If so, then please
	simply attach the stripped version of the document, not all 1000 pages
	.... </p>

	<h4><a name="attachments"></a>Use attachments where possible</h4>
	<p> Don't paste large files into the description. For instance, if
	you're asked to provide a stack of a crash, copy this stack into a
	file, then <span style="text-decoration: underline;">attach</span>
	this file. If you have some Basic macro or Java code which triggers a
	problem, copy it into a separate file, and <span
	style="text-decoration: underline;">attach</span> this file. </p>
	<p> The reason here is simple: A 3-pager within the description of an
	issue makes reading the issue really difficult. Everybody who wants to
	get an impression of the issue needs to scan through a lot of
	information which, though definitely important, is of only peripheral
	interest for them at the moment. </p>

	<h4><a name="complete"></a>Put all relevant information into the issue</h4>
	<p>Don't use (only) links to refer to the bug descriptions. Links tend to become outdated
	over time, so if half a year later, somebody looks at your issue, it has become meaningless.
	</p>

	<p>If there is some external resource describing your problem - fine, link it! But don't rely
	on links as the <em>only</em> mean for bug descriptions - copy the information which is
	necessary to reproduce the problem into the issue.</p>

	<hr/>
	The author of the original document is <a
	href="mailto:fs@openoffice.org">Frank Schönheit</a>. Constructive
	<a href="mailto:fs@openoffice.org">feedback is welcome</a>. You may
	also consider visiting <a href="mailto:qa@openoffice.apache.org"> the
	mailing list</a> dedicated to discussing issue handling.
	<hr/>
	<div> </div>
	</div>
	</body>
	</html>