Bugzilla Guide

From NeoWiki

Contents 1 I've found a bug or have a feature request for NeoOffice/J. What should I do? 1.1 Before reporting a bug in NeoOffice/J... 1.2 Feature Enhancements 2 Filing a bug report in the NeoOffice.org Bugzilla 2.1 Obtaining a crashlog or sample 2.1.1 Obtaining a crashlog when NeoOffice/J crashes 2.1.2 Obtaining a sample when NeoOffice/J hangs (displays the spinning beachball) 3 Things to Do

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

Before reporting a bug in NeoOffice/J...

1. Make sure you are using the latest patch; visit http://www.planamesa.com/neojava/patch.php to download the latest patch. Our talented volunteer developers are contstantly fixing bugs, and your bug might have been fixed already.
2. 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 the NeoOfficeJ-1.1 folder in your user's Library folder to another location and restart NeoOffice/J.
   3. If you have access to the X11 version of OpenOffice.org, see if the bug reproduces there; if so, file a bug report in the OpenOffice.org IssueZilla instead, since it is an OpenOffice.org bug.
3. If the problem bug persists, file a bug, following the guidelines below.

Feature Enhancements

We are not currently taking requests for feature enhancements. Due to the rapid changes in the nature of the Macintosh platform and the available developer time and resources, the scope of the NeoOffice/J project is limited at this time to keeping a native version of OpenOffice.org running on Mac OS X. See this thread on trinity for more details: http://trinity.neooffice.org/modules.php?name=Forums&file=viewtopic&t=1481

Fixing OpenOffice.org feature bugs is outside the current scope of the project, as are enhancements. Many enhancements need to be implemented in shared OpenOffice.org code and should be filed in the OpenOffice.org IssueZilla instead.

Filing a bug report in the NeoOffice.org Bugzilla

1. Before filing a bug, search for a duplicate to make sure the bug hasn't already been reported.
   • Select Query Bugs from the main page of Bugzilla.
   • Select NeoOffice/J from the Project menu and enter search terms.
2. When filing a bug, include only one issue (bug) per report; this makes it easier to track and fix bugs.
3. Make sure you select the appropriate version of Mac OS X and include the patch version of your NeoOffice/J application
   • The patch level is located in the "About" box accessible from the NeoOffice/J menu
   • The Mac OS X version is located in the "About This Mac" box accessible from the Apple menu
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.
5. Attach supporting documents (screenshots, crash logs, sample documents, etc.) after submitting the bug; the "Create New Attachment" link is only present after the bug is submitted.
   • Attach a screenshot, if relevant
   • Attach the problematic document, if relevant, or email it to Patrick if it is sensitive

     N.B. Add attachments separately from comments (adding an attachment wipes out unsubmitted comments)

6. If you are reporting a crash or a hang (beachball), attach (do not paste into the comments) a crash log or a sample; see instructions below.

Obtaining a crashlog or sample

Obtaining a crashlog when NeoOffice/J 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/J 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:" textarea and paste into a new plain-text document (in TextEdit, create a new document and choose "Make Plain Text" from the "Format" menu).
  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 isn't showing on the left.
  3. In the list of logs on the left, select "~/Library/Logs" then "CrashReporter" then "soffice.bin.crash.log"
  4. 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.
  5. Select the entry, from the "Host name" down to the end of the entry and paste into a new plain-text document (in TextEdit, 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.

  6. Attach this crashlog to the bug you filed.

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

1. Do not "force quit" NeoOffice/J
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/J 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/J entered the hung state.
7. When the sample is complete, save the file; you may now close the sample window and force quit NeoOffice/J.
8. Attach the saved sample to the bug you filed.

Things to Do

1. New front page (bypassable for certain users, i.e. admins or long-time good bugfilers) or something like Bugzilla Helper
   • Steps to take before filing a bug
     • Install latest patch [link]
     • Reboot
     • Fresh profile

     I.e., is it reproducible, esp. in up-to-date stock conditions

     • Attempt to reproduce in corresponding version of OOo/X11 if possible (?)
     • Search for duplicate (select NeoOffice/J from the Project menu)
   • Scope of bugs, i.e. what's a Neo/J bug vs. an OOo bug/limitation vs. an Apple bug/limitation
   • How to submit a useful bug report
2. Write "How to submit a useful bug report"
   • One issue per bug report
   • Include Patch level and OS version
     • About NeoOffice/J in the Neo/J menu; About This Mac in the Apple menu
   • Provide crashlog for crashes and sample for hangs - Camino crash/hang FAQs

     sardisson wrote the crash/hang FAQs for Camino, so we just need to copy them over here and tweak for the NeoBugzilla

     • How to get a crashlog to attach
       • Option A: is crashreporter enabled?
         • When "Unexpectedly quit" dialogue appears, select "Submit Report..."
         • Copy/paste "Crash Report:" section into new text file.
       • Option B: the hard way
         • Open Applications > Utilities > Console
         • Click on the "Logs" toolbar icon if the logs drawer isn't showing on the left.
         • Navigate through the list until you get to ~/Library/Logs > CrashReporter > soffice.bin.crash.log
         • Locate the appropriate log for the most recent/remembered crash. It should be the one at the bottom. Each individual crash log is separated by a line of asterisks from the next one above it; each one has a date at the top of it.
         • Copy from the "Host name" down to the end. Edit > Copy. Places a copy of the log onto the Clipboard
         • Open TextEdit and create a new plain-text file. Paste the crashlog. (Hmm, isn't there an "export" function in Console.app that will grab the last log entry?)
     • How to get a sample to attach
       • Open Applications > Utilities > Activity Monitor
       • Select Neo/J from list of running processes
       • Click "Inspect" button
       • Click "Sample" button (lower left corner of resulting window)
       • When sampling is completed, save resulting text file
   • Attach (not paste) crashlog or sample
     • After bug is filed
     • Add attachments separately from comments (attachment refresh wipes comments, currently no warning); add warning on bug pages along the lines of the text in the OOo IssueZilla:

       Note: please commit any changes to this issue before creating a new attachment, or changes will be lost.

   • Detailed steps to reproduce
   • Attach screenshot if relevant
   • Attach problematic document, if relevant, or email it to Patrick if sensitive
   • Example of a pretty solid report: http://bugzilla.neooffice.org/bug.php?op=show&bugid=554
   • Oscar provides two links to general "good bug-filing behavior" articles. We should be sure to include the highlights and perhaps link to them "for more details" or something:
     • How to Report Bugs Effectively
     • How To Ask Questions The Smart Way (a much longer piece also dealing with general "getting support/answers" issues)
3. Change Advanced Query to be the default search

   Basic query is absolutely useless for finding duplicates! I'm having better luck with basic query now

   (select NeoOffice/J from the Project menu)