Bugzilla Guide

From NeoWiki

Revision as of 05:29, 9 June 2015

A guide to filing and triaging NeoOffice bugs

I've found a bug or have a feature request for NeoOffice. What should I do?

Before reporting a bug in NeoOffice...

1. Make sure you are using the latest patch; visit http://www.neooffice.org/neojava/patch.php to download the latest patch. Our talented volunteer developers are constantly fixing bugs, and your bug might have been fixed already.
2. Check the Troubleshooting Tips for any troubleshooting steps or solutions relevant to the problem you are experiencing.
3. Disable or uninstall any "haxie" software, such as InputManagers, SIMBL "plugins", or haxies that use Unsanity's Application Enhancer (APE) framework.
4. See if you can reproduce the bug (repeatedly cause the bug to occur); bugs that are not reproducible are very difficult to fix.
   1. See if the bug is reproducible after rebooting your Mac.
   2. See if the bug is reproducible "with a fresh profile"; sometimes your user settings can become corrupt and cause a bug. Move your user's ~/Library/Preferences/NeoOffice-x.x folder to another location and restart NeoOffice.
   3. If you have access to the Mac version of OpenOffice.org, see if the bug reproduces in the corresponding OpenOffice.org version (e.g., NeoOffice 2.2.5 is equivalent to OpenOffice.org/X11 2.2.1 and NeoOffice 3.0 is equivalent to OpenOffice.org Aqua 3.0.1); if so, file a bug report in the OpenOffice.org IssueZilla instead, since it is an OpenOffice.org bug.
5. If the problem persists, report a bug in the NeoOffice Support forum, following the guidelines below.

Feature and Enhancement Requests

Unfortunately, our very limited funding and developer resources limits the current scope of the NeoOffice project to keeping a native version of OpenOffice.org running on Mac OS X and fixing OpenOffice.org bugs is outside that scope. Similarly, most enhancements need to be implemented in shared cross-platform OpenOffice.org code and should be filed in the OpenOffice.org IssueZilla instead.

Filing a bug report in the NeoOffice Support forum

If you found a bug, please post your bug in the NeoOffice Support forum. If NeoOffice is crashing or hanging, we recommend that you obtain a crash log or sample by following the steps in this NeoWiki article and then attach the crash log or sample to your post using the instructions in this post.

We will evaluate any bugs that are posted in the NeoOffice Support forum. If we find that a change in the NeoOffice code is needed, a NeoOffice developer will create a bug for you.

1. When filing a bug, include only one issue (bug) per post; this makes it easier to track and fix bugs.
2. Make sure to include the following information; version of NeoOffice and Patch number, Mac OS X version and whether your Mac has an Intel or PowerPC processor.

   This helps us determine if the bug only exists on a particular version of Mac OS X and at which patch level the bug began to appear.

   • The NeoOffice version and patch level is located in the "About" box accessible from the NeoOffice menu; if you are not using the latest patch, you will be instructed to install the latest patch.
   • The Mac OS X version and processor information is located in the "About This Mac" box accessible from the Apple menu.
3. Choose a brief but descriptive summary for your bug, e.g.
   • If you are having a problem where the date will not display in the footer, a summary of "Date in footer doesn't display" is useful, while a summary of "footer" is not.
   • If you are having a problem where you are unable to insert columns in Calc, a summary of "Can't insert new columns" is useful, while a summary of "insert columns" is not.
4. Provide detailed steps to reproduce (cause) the bug; developers will need these steps to help them determine what causes the bug so that they can fix it.

   Note that OpenOffice.org and thus NeoOffice is a huge program, and the developer or QA team member working on your bug may not be familiar with the part of the program in which you've discovered the bug. Thus the more detailed steps you can supply, the more likely someone will be able to do something useful with your bug report.

5. Attach supporting documents (screenshots, crash logs, sample documents, etc.) using the instructions in this post.
   • Attach a screenshot, if relevant.
   • Attach the problematic document, if relevant, or a sample document on which to demonstrate the issue. The site is public so do not attach documents with sensitive or proprietary information.
6. If you are reporting a crash or a hang (beachball), attach (do not paste into the comments) a crash log or a sample.
7. If a NeoOffice developer creates a bug in Bugzilla, you can add yourself to the cc: list of the bug to track its progress. If you do not already have an account on the NeoOffice Bugzilla, you will need to create one before you can add yourself to the cc: list.
   N.B. Accounts on Bugzilla are separate from any other NeoOffice accounts you might have (e.g. Early Access Program, trinity, or this wiki).

Obtaining a crashlog or sample

Obtaining a crashlog when NeoOffice crashes

• Option A: is CrashReporter enabled?

  Mac OS X has a great application called CrashReporter which generates crash reports when applications crash. It is enabled by default on Mac OS X.

  1. When the dialogue stating "The application NeoOffice has unexpectedly quit" (or "The application soffice.bin has unexpectedly quit") appears, click the "Submit Report..." button.
  2. Copy the entire contents of the "Crash Report:" text box. Open the TextEdit application; from the menu bar select File then New to create a new document, next from the menu bar select Format and then Make Plain Text; now paste the text into window. Save file, naming it crash_log.txt. (This is a plain-text document.)
  3. Once you've saved the text file, you can dismiss the Crash Report dialogue.

     N.B. The wording of the dialogues vary between major Mac OS X versions.

  4. Attach this crashlog to the bug you filed.
• Option B: the hard way (you've probably disabled CrashReporter)
  1. Open the Console application, located in the Utilities subfolder of the Applications folder.
  2. Click on the "Logs" toolbar icon if the logs drawer (sidebar) isn't showing on the left.
     • On Mac OS X 10.5 or newer, follow these steps to find and copy the correct crash report:
       1. Select "~/Library/Logs" in the "LOGS" section, then "CrashReporter", and finally the "soffice.bin_2009-03-06-190511_ComputerName.crash" log (where 2009-03-06-190511 represents the date and time the crash occurred and ComputerName is your computer name or hostname).
       2. Select the entire contents of the crash report and copy to the clipboard.
     • On Mac OS X 10.4.11 or older, follow these steps to find and copy the correct crash report:
       1. In the list of logs on the left, select "~/Library/Logs" then "CrashReporter" then "soffice.bin.crash.log"
       2. Locate the appropriate log entry for the most recent crash. It should be the one at the bottom. Each individual crash log entry is separated by a line of asterisks from the next one above it; each entry has a date at the top of it.
       3. Select the entry, from the "Host name" down to the end of the entry and copy to the clipboard.
  3. Paste the copied crash report information into a new plain-text document (in the TextEdit application, create a new document and choose Make Plain Text from the Format menu).

     N.B. The format of the crashlog varies between major Mac OS X versions.

  4. Attach this crashlog to the bug you filed.

Obtaining a sample when NeoOffice hangs (displays the spinning beachball)

1. Do not "force quit" NeoOffice
2. Open the Activity Monitor application, located in the Utilities subfolder of the Applications folder.
3. On launch, Activity Monitor should display a window listing various "processes" that are running on your Mac.
4. Select NeoOffice from the list of running processes.
5. Click the "Inspect" button.
6. In the window that opens, click the "Sample" button in the lower left corner; this will generate a "sample" that will help the developers determine why NeoOffice entered the hung state.
7. When the sample is complete, save the file; you may now close the sample window and force quit NeoOffice.
8. Attach the saved sample to the bug you posted.

In some cases, a Shark profile will be more useful. If the developers ask you for a Shark profile, instructions on capturing one are available in this post on trinity.

Further Reading on Reporting Bugs

The following documents written by others provide further discussion of general "good bug-filing" practices:

• How to manipulate me (or, Tuesday Whipper-Snapping) (Brent Simmons, author of the most popular desktop feed reader, NetNewsWire)
• How to Report Bugs Effectively (Simon Tatham, professional and free-software programmer; several translations)
• How To Ask Questions The Smart Way (Eric S. Raymond, open source advocate; a much longer piece also dealing with general "getting support/answers" issues, also with several translations)

Life-cycle of a Bug

This section explains each of the "states" a bug can have in Bugzilla and how bug moves from state to state. Both Bugzilla's "Status" and "Resolution" fields are explained.

Unconfirmed

All bugs begin with a status of "Unconfirmed" and a resolution of "None".

From "Unconfirmed", bugs usually end up "Reproducible but not assigned" if they are reproducible problems specific to NeoOffice, "Closed" as "Duplicate" if another bug covering the same problem has already been reported, or "Closed" as "OpenOffice.org bug" if the bug also exists in the equivalent version of OpenOffice.org/X11. Bugs "Closed" as "OpenOffice.org bug" should be entered by the reporter in the OpenOffice.org IssueZilla in order to ensure the OpenOffice.org developers responsible for the issue fix it, and the person closing the bug should prompt the reporter with this information:

Sometimes "Unconfirmed" bugs are also "Closed" as "Not a bug" (if a feature works as designed, even if that is not the way the reporter thinks it should work), "Closed" as "Won't fix" (most often bugs in Mac OS X or Java, which can't be fixed except by Apple, or feature enhancements), or "Closed" as "Works for me" (if no one else can reproduce the bug and/or there is insufficient information in the bug report to determine the cause). In 2005 and 2007, additional resolutions were added to cover bugs in external code not derived from OpenOffice.org itself or when there is insufficient information and the reporter is non-responsive. See the Closed section below for more on when and how to use these resolutions.

Duplicates

When bugs are "Closed" as "Duplicate", the number of the duplicated bug is added to the "Add Dependency" field of the bug that is being closed, e.g., if bug 1060 is a duplicate of bug 1048, enter 1048 in the "Add Dependency" field of bug 1060 when setting it to "Closed".

Bugs can be duplicates of other bugs that are "Assigned", "Fixed" (if the reporter is not using the latest version or patch), "Reproducible but not assigned" (formerly "New"), or "Closed" (all resolutions except "Duplicate"; a bug cannot be a duplicate of a duplicate, so the bug is marked as a duplicate of the original bug).

If a bug is a duplicate of another "Unconfirmed" bug, that is sometimes enough to warrant changing the the first bug to "Assigned"—but see below for additional items a bug really should have before being set to "Assigned". In the case of two "Unconfirmed" bugs that are duplicates of each other, usually the oldest bug is set to "Assigned" and the newer one marked as the duplicate. However, if the newer bug has a clearer bug report, more information, supporting documents, etc., then the newer bug should be set to "Assigned" and the older one closed as a duplicate of the newer one.

Reproducible but not assigned

This status (formerly "New") is for bugs that have been successfully reproduced by a member of the triage team. Generally bugs need a clear set of instructions to reproduce the problem as well supporting "documentation" (screenshot, sample document, Mac OS X crashlog or sample, etc.) before they are changed from "Unconfirmed" to "Reproducible but not assigned". Developers then will query this list of bugs and assign bugs to themselves as they have time to fix the bugs, focusing on the most critical bugs first.

This status is also a holding place for bug that the developers intend to fix but for one reason or another cannot fix at the moment; these bugs carry the resolution "Deferred".

Often bugs are assigned this status ("Reproducible but not assigned" with resolution "Deferred") due to problems in supporting software (Mac OS X or Java) that we know are resolved in a future version of the supporting software and can be fixed when users or NeoOffice upgrade to the newer version.

Assigned

Bugs that are actively being worked on by a NeoOffice developer have status "Assigned", and the "Assigned To" field will show the email address of the developer working on the bug.

Most "Assigned" bugs are changed to status "Resolved" with a resolution of "Fixed", but bugs that cannot be fixed at the moment, or that can be fixed but are of a low priority and are not actively being worked on, are changed to "Reproducible but not assigned" (formerly "New") with a resolution of "Deferred". "Assigned" bugs can also be changed to "Closed" as "Not a bug" or "Closed" as "Won't fix" after the developer investigates the issue and determines the problem lies elsewhere or cannot be fixed.

"Assigned" bugs that a developer has fixed often remain in the "Assigned" state (recently as "Assigned" with resolution "Fixed" to help them stand out in large "Assigned" lists) until the fix appears in an official patch, at which point they are set to status "Resolved" and resolution "Fixed" (and, once the fix appears in a completely new binary, to status "Closed" and resolution "Fixed"); in any case, only developers should modify the status or resolution of bugs that are "Assigned" or "Resolved".

Resolved

Bugs that are fixed are "Resolved" as "Fixed" once the developer has coded a solution that fixes the bug and has released an office "patch". If a patch does not fix a bug, it becomes "Reopened"; once the fix for the bug has been included in a full downloadable build of NeoOffice (a "release", such as NeoOffice 2.1), a bug is "Closed". (Only the release engineer should change a bug from "Resolved Fixed" to "Closed Fixed"; this ensures that the fix is present in the final release and no bug gets overlooked.)

Reopened

If a bug that was "Resolved" as "Fixed" turns out not to have been fixed by a patch, the reporter of the bug should change the bug's status to "Reopened" and set the resolution back to "None".

If a bug that was "Closed" as "Works for me" is still present and the reporter has new information or better steps to reproduce the bug, it should also be changed to "Reopened" and "None" (technically it should be set back to "Unconfirmed" and "None" until someone can reproduce the bug, but our bugzilla is "manual" and doesn't have the "automatic" logic to do that).

Closed

"Closed" is the final status of all bugs in the NeoOffice Bugzilla. Bugs that have been fixed and whose fixes have appeared in a full release of NeoOffice are set to "Closed" and "Fixed".

Bugs that were "Closed" without being fixed have one of the following resolutions:

• "Closed" as "Duplicate", if another bug covering the same problem has already been reported; see the subsection on Duplicates under "Unconfirmed" for more information
• "Closed" as "OpenOffice.org bug", if the bug also exists in the equivalent version of OpenOffice.org/X11.

  Reporters should be prompted to file the bug in the OpenOffice.org IssueZilla, since NeoOffice developers do not have the time to forward all of these bugs back to OpenOffice.org.

• "Closed" as "Not a bug", if a feature works as designed, even if that is not the way the reporter expects the feature to work, or if the bug is caused by third-party software (other than the specific software with custom resolutions in Bugzilla, e.g. "Mac OS X bug").
• "Closed" as "Won't fix", usually when the bug is really in Mac OS X or Java, which can't be fixed except by Apple, or bugs which want a behavior not desired by the developers or the majority of the userbase.
• NEW "Closed" "Mac OS X bug", if the issue is caused by a bug (or feature) of Mac OS X.
• NEW "Closed" "ooo-build bug", if the issue is caused by a bug (or feature) of code integrated from the ooo-build project (Excel VBA macros, Calc Solver).
• NEW "Closed" "odf-converter bug", if the issue is caused by a bug (or feature) of code integrated from the odf-converter project (MS OpenXML import/export).

  Bugs closed as "ooo-build" or "odf-converter" bugs should be reproducible, with necessary supporting documentation. NeoOffice developers will periodically query these bugs and either fix the bugs or forward them to the appropriate project's bug tracker.

• NEW "Closed" "Insufficient info", if the issue cannot be reproduced with the existing comments from the reporter and prompting the reporter for more information has produced no results.
• "Closed" as "Works for me", if no one else can reproduce the bug or if something that seemed to be a bug suddenly seems fixed with no clear fix on the part of NeoOffice developers.

Other open source project bug

Bugs that are found to be caused by bugs in code that NeoOffice has included from another open source project will have this status and the "Resolution" field will be set to the open source project that is the cause of this bug.

"Other open source project bugs" should always have a link to the bug filed with the other open source project. If the other project eventually fixes the bug, a developer will assign it to themselves and the status will change to "Assigned".

Chart

The following chart provides a graphical explanation of a bug's life-cycle. N.B. A number of the resolutions marked NEW above are not shown on this chart.