| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| <title>Issue Writing Guidelines</title> |
| </head> |
| <body> |
| <div class="app"> |
| <h2>Issue Writing Guidelines</h2> |
| <p><i>Last updated 2004-01-06<br> |
| <br> |
| </i> |
| </p> |
| <h4>Consider the rules<br> |
| </h4> |
| <p>We strongly encourage you to read the <a href="basic_rules.html">Basic |
| IssueTracker rules</a> - for those who work with IssueTracker on a day-by-day |
| base, they have proven to |
| <span style="font-style: italic;">immensely</span> |
| reduce their work. It's really easy for you to report issues in a way which |
| cost all others a lot of time, but if you invest a little more effort in the |
| beginning, you save others a lot thereof afterwards.<br> |
| </p> |
| <p>Thus, if you're new to OpenOffice.org's IssueTracker, please <a href="basic_rules.html"> |
| read the rules</a>. And, of course, please follow them :-), to make our all |
| work easier, so we can concentrate on improving the product, instead of wasting |
| time with bad issue reports.</p> |
| <p>And, please don't take be offended if we ask you to follow <a href="basic_rules.html"> |
| some rules</a>: Simply put, the more effectively you report an issue, the |
| more likely an engineer will actually fix it, and this is what we all are |
| interested in. |
| </p> |
| <h4>How to Write a Useful Issue Report</h4> |
| <blockquote> |
| <p>Useful issue reports are ones that get issues fixed. A useful issue report |
| normally has two qualities:</p> |
| </blockquote> |
| <ol> |
| <li> |
| <b>Reproducible.</b> 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. |
| </li> |
| <br> |
| <li> |
| <b>Specific.</b> 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.) |
| </li> |
| </ol> |
| <blockquote> Let's say the application you're testing is a spreadsheet |
| application. You crash at when you open the file foo.sxc, and want to write up |
| an issue report: </blockquote><blockquote> <b>Bad:</b> "My spreadsheet crashed |
| when I tried to open a document. I think it contained a chart. 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 has a problem with the word |
| processor. Nothing works right, either. Good luck." |
| <br> |
| <br> |
| <b>Good:</b> "I crashed each time when I opened the attached spreadsheet |
| document using the 10.13.00 build on a Win NT 4.0 (Service Pack 5) system. I |
| also rebooted into Linux (RedHat 6.2), and reproduced this problem using the |
| 10.13.00 Linux build. |
| <p>When I removed the chart from the document I was able to load it without any |
| trouble." |
| </p> |
| </blockquote> |
| <h4>How to enter a useful Issue Report into IssueTracker</h4> |
| <blockquote> In order to file an Issue, you must be a registered user of |
| OpenOffice.org. Registering is easy: simply click on the "Join" link in the |
| left navbar and follow the instructions. It takes all of a few minutes. If you |
| are a registered user, click on the "My Issues" link in the left navbar or on |
| the <a href="project_issues.html" target="_blank">"Bugs and Issues"</a> link on |
| the navbar. The latter is a more comprehensive page which provides a |
| explanation of IssueTracker and also has some useful IssueTracker links, such as a |
| query link. |
| <p> |
| Go to the <a href="http://www.openoffice.org/issues/query.cgi" target="_blank">IssueTracker |
| Query Page</a> 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.)<br> |
| <br> |
| If you've discovered a new issue using a current build, report it in |
| IssueTracker: |
| </p> |
| <ol> |
| <li> |
| If you're not already logged in, please enter your username & password in |
| the appropriate filds at the top of this page (or any other page on this site)</li> |
| <li> |
| From your IssueTracker main page, choose "Enter a new issue".</li> |
| <li> |
| Select the product that you've found an issue in.</li> |
| </ol> |
| <p>regarding 2., there is a link "File Issue" as well, accessible from the "My |
| Pages"-tab (When logging in you're automatically directed to "My Pages", you |
| can then access issueTracker using the links in the "My Tools" box on the left |
| side of your screen)</p> |
| </blockquote> |
| <h4>Now, fill out the form. Here's what it all means:</h4> |
| <blockquote> <i>Where did you find the issue? </i></blockquote><blockquote> <b>Product: |
| In which product did you find the issue?</b><br> |
| You just filled this out on the last page. </blockquote><blockquote> <b>Version: |
| In which product version did you find the issue?</b><br> |
| If applicable. </blockquote><blockquote> <b>Component: In which component does |
| the issue exist?</b><br> |
| IssueTracker 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.) </blockquote><blockquote> <b><a href="http://www.openoffice.org/scdocs/ddIssues_EnterModify.html#platform"> |
| Platform</a>: On which hardware platform did you find this issue? </b>(e.g., |
| 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. </blockquote><blockquote> <b>OS: On which Operating System |
| (OS) did you find this issue?</b> (e.g. Linux, Windows NT)<br> |
| If you know the issue happens on all OSs, choose 'All'. Otherwise, select the |
| OS that you found the issue on, or "Other" if your OS isn't listed. </blockquote> |
| <blockquote> |
| <br> |
| <i>How important is the issue? </i></blockquote><blockquote> <b><a href="http://www.openoffice.org/scdocs/ddIssues_EnterModify.html#issuetype"> |
| Issue Type</a>: Is this a defect, enhancement, feature-request, task or |
| patch?</b><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> |
| <blockquote> <b><a href="http://www.openoffice.org/scdocs/ddIssues_EnterModify.html#priority"> |
| Priority</a>: How urgent is a fix required?<br> |
| </b>This item defaults to '3'. 1 is the highest, 5 the lowest priority.</blockquote> |
| <blockquote> |
| <br> |
| <i>Who will be following up on the issue?</i> </blockquote><blockquote> <b><a href="http://www.openoffice.org/scdocs/ddIssues_EnterModify.html#assignedto"> |
| Assigned To</a>: Which engineer should be responsible for fixing this issue?</b><br> |
| IssueTracker 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.) </blockquote><blockquote> <b>Cc: Who |
| else should receive e-mail updates on changes to this issue?</b><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><blockquote> |
| <br> |
| <i>What else can you tell the engineer about the issue? </i></blockquote><blockquote> |
| <b>URL: On what URL did you discover this issue?</b><br> |
| If you encountered the issue on a particular URL, please provide it (or, them) |
| here. </blockquote><blockquote> <b>Summary:</b> <b>How would you describe the |
| issue, in approximately 60 or fewer characters?</b><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 "Abort trying to install on RedHat 7.0, Kernel 2.2.14" is a useful |
| title. "Software fails" or "install problem" would be examples of a bad title. </blockquote> |
| <blockquote> |
| <br> |
| <b>Description: What else can you tell the engineer about this issue?</b><br> |
| Please provide as detailed of a problem diagnosis in this field as possible. A |
| precise step-by-step description is the best way to do it.<br> |
| For crashing issues it might help to have additional information in case you're |
| able to provide that:</blockquote><blockquote><br> |
| <b><a href="http://www.openoffice.org/scdocs/notargetmilestone.html">Target |
| Milestone</a>:</b> Think of it as a deadline; targets are "not determined" |
| or "next build"--for most issues, stipulate "not determined." |
| <ul> |
| </ul> |
| <p><strong>Attachments.</strong><em> </em>It may be the case you need to add an |
| attachment(s) to an Issue, either the one you file or another one. You can do |
| it; the limit is 10MB, but please keep any attachment small, as most people use |
| 56K connections. Attaching a file to an issue is a two-step procedure and is |
| not obvious. You must first submit the issue or locate the issue to which you |
| wish to attach the file. Then, you can add the file as an attachment to that |
| issue. There will be a link in the issue body that reads: |
| </p> |
| <blockquote> Create a new attachment (proposed patch, testcase, etc.)</blockquote> |
| <p> |
| <strong>Note</strong>: You cannot add OpenOffice.org files natively. They must |
| be added as "binary" files. This is a temporary problem. |
| </p> |
| <p> |
| Hints: Reduce the size of your file as much as possible. And, if you are |
| uploading an HTML document, be sure to compress it first (Zip or tar it), |
| otherwise it gets corrupted when others try to download it. |
| </p> |
| <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 IssueTracker |
| database.<br> |
| </p> |
| <hr> |
| <p>(These Bug Writing Guidelines were originally written for Mozilla by <a href="mailto:eli@prometheus-music.com"> |
| <b>Eli Goldberg</b></a>. Thanks to Claudius Gayle, Peter Mock, Chris Pratt, |
| Louis Suarez-Potts, Tom Schutter, and Chris Yeh for contributing to this |
| document. Constructive <a href="mailto:michael.bemmer@germany.sun.com">suggestions |
| and feedback</a> are welcome.) |
| </p> |
| </blockquote> |
| </div> |
| </body> |
| </html> |
