2001 Telsa Gwynne 2002 Kevin Conder 2002 Eric Baudais GNOME Documentation Project &legal; Telsa Gwynne GNOME Documentation Project

telsa@linuxchix.org

Kevin Conder GNOME Documentation Project

kevin@kevindumpscore.com

Eric Baudais GNOME Documentation Project

baudais@kkpsi.org

&app; Manual V&manversion; &date; Eric Baudais baudais@kkpsi.org GNOME Documentation Project &app; Manual Telsa Gywnne telsa@linuxchix.org GNOME Documentation Project This manual describes version &appversion; of &app;. &app; is a tool which will guide you through making a bug report as painlessly as possible. You can alter things at any stage, and then either send, save, or abandon the resulting report. This document describes version &appversion; of &app;: note that it has changed substantially in appearance from earlier versions. Bug Buddy has undergone major changes recently. The Gnome bug tracking system is moving from the email-based debbugs installation which it originally used to the web-based bugzilla installation. This is to help deal with bugs more efficiently. This means Bug Buddy has been substantially rewritten to deal with the bugzilla system. It looks very similar in appearance and structure, but be aware that it now talks to bugzillas. Reports will only go to the old debbugs system for GNOME if bugzilla doesn't have a category for the bug. This also means that Bug Buddy has currently lost the ability to send bugs to the KDE and Debian bug trackers directly. Note that you can still save reports for those into a file and then mail the file to those trackers yourself. &app; can be started in a variety of ways: Open the main GNOME menu and select Applications Programming Bug Report Tool . Run bug-buddy at the prompt in a terminal such as gnome-terminal or xterm. If you are using Nautilus you can double-click your mouse on a core file to start it. When a GNOME program experiences a bad crash, a crash dialog box is displayed. If &app; is present on the system, then one of the options in the dialog box will be to make a bug-report. Selecting that will lead you to a further dialog box giving you details of the program which crashed. Continuing at this stage will invoke Bug Buddy . &app; is a very structured program. At any stage you can continue forward or head backwards to correct earlier details, or you can click the Help button to bring up this document. The aim of all this is to be able to collect all the information which a developer will need to reproduce the same problem and be able to fix it. Some of the information generated may look a bit off-putting, but don't delete it. It will be useful. &app; opens with a welcome and some important buttons at the bottom of the screen. The four buttons at the very bottom of the screen will not change in &app; while using the program. The About button gives information about &app;'s version and copyright holders. There is a Credits button in the About Bug Buddy dialog which lists the authors of the program and documentation. The Cancel button is used to exit &app; and cancel the bug report. The Cancel button brings up the Question dialog which asks if you really want to exit the program. Pressing the No button will close the dialog and bring you back to the program so you can continue your bug report. Pressing the Yes button will close the program and cancel the bug report you were making. The Back button will bring up the previous screen so you can change your report. The Forward button will bring up the next screen to continue your bug report. In &app;'s startup window the Show Debugging Options button shows the debugging options available. This allows you to perform back traces on a crashed application or to include the core file created when the application crashed. &app; will add the back trace or core file to the bug report automatically. If you do not want to include the back trace or core file you can delete them in the . You can also copy the output of &app;'s debugging window to the clipboard or save it as a file. &app; has three options when writing a bug report. When you are done with the debugging information click on the Forward button to proceed to the next step in submitting your bug. Debug nothing This is the default option. If you did not start Bug Buddy following a crash, and do not have a core file you want debugged, pick this. Debug core file If &app; began because you double-clicked on a file named core in the file manager, select this. Also select this if you have a core file which you know was created as a result of the bug you are reporting. An extra box will appear where you can tell it where the core file lives. Debug crashed application If Bug Buddy began because you said yes to Report a bug in a dialog box telling you something had crashed, select this. If you do so, you will be prompted for two things. These should be filled in already for you. If they are not, take a moment to fill in: Binary: In this box you must type the name of the program as you would type it at the command-line. For example, if Nautilus crashed, you would need to type nautilus here. Process ID: In this box you must type the process ID or PID. This will probably be available from the original dialog box where you selected Report a bug. If you have closed that window, you can find it by starting the Procman System Monitor through selecting Applications System Tools Procman System Monitor or typing procman at the command line. You will find the PID in the right-hand column and the command in the left-hand column. This page gives you a list of products, from which you can select. Select the product you want to report a bug in and click on the Forward button to proceed to the next screen. If you wish to submit a bug, but the product isn't listed then click on The product is not listed above checkbox. You will skip the Component section and proceed directly to the . If this is the first time you have run Bug Buddy, you will see this page. It also appears if it has been two weeks since the last update. Otherwise it will not appear. A dialog box telling you Bug Buddy wants to update its list of information will appear and gives you the option to stop or configure the proxy settings. It will save this information by default into your .gnome2/bug-buddy.d/ directory. To get this information, it needs to talk to bugzilla, so your net connection will have to be up. There are three sections to fill in: Component The product selected will have one or more components to it. If there is only one component (typically a general component), click on it. If there are several components, select the most likely looking one. Version This is the version number for the program or package you're reporting a bug in. It may already be filled in. If not, find out the version through the package's About ] box and fill it in here. Severity This is the severity of the bug, as you feel it. There are several choices in decreasing order: An enhancement bug is a request for enhancement rather than a bug describing a problem. "It would be nice if.." A trivial bug is precisely that: trivial. It is typically a cosmetic problem such as misspelled words or misaligned text. A minor bug involves either a minor loss of function, or a larger problem but one which has an easy workaround. A normal bug is the typical sort of bug. This is the default and probably won't need increasing. A major bug involves a major loss of function. A critical bug is one which involves a crash, a severe memory leak, or loss of data. A blocker bug is rare and usually assigned as a blocker by a developer. It is a bug which stops other things being fixed and which must be fixed before other bugs can be closed. When all three sections are filled in, the Forward button will become enabled, and you can continue. There isn't any information to fill in, but take a moment to look at the bugs displayed here. These bugs are the most common bugs reported in all of GNOME. Look at the product and description to determine if the bug you were going to report is similar to any of the bugs displayed here. If you bug matches one of the bugs or is reasonably close you can click on it to bring up bugzilla in your browser. Then you should add a comment to the existing bug instead of filing a new bug. If none of the bugs displayed here look like the bug you are going to report then click on the Forward button to continue to the next section. There are four sections which need to be filled in: Summary for the bug report The Summary section will be used as the Subject header of the emailed bug report, which will turn into a Summary line in Bugzilla. Good subject lines are specific and do not just say Bug or It crashed. Crash when I try to save or Forgets my preferences are much better. Hackers will read these summaries when looking for something they can fix and clear one-sentence summaries will catch their attention. You must fill this in. If you do not, &app; will tell you to. Full description of the bug The Description section is where you describe what happened, what you did, and what you expected to happen. You should write good concise sentences describing the bug as best as you can. The section is divided into three parts: Description of Problem: The Description of Problem section is where you describe what happened. The bug produced some unexpected behavior and you should describe exactly the unexpected behavior. This includes any error messages or warnings. Steps to reproduce the problem: The Steps to reproduce the problem section is where you describe what you did to make the bug appear. You should use short sentences telling exactly what you did to produce the bug. Be as particular as possible in this section to describe exactly each step you took to produce the bug. Developers will use your instructions to try and reproduce the bug on their systems. Actual Results The Actual Results section is where you describe what you expected to happen. The bug stopped you from doing something and you should describe what you wanted to happen here. It can as simple as, (I expected the application to load a PNG file). Other good things to include: Exact copies of any error messages; Your window manager name and version (especially if the bug involves moving things around the screen or mouse focus problems); Any special versions of binary RPM, debs, or GNOME specific versions such as Ximian GNOME or Garnome. Include the name and the version you installed; If you can make it happen in one way, and not in another way, include that. If there are two ways to do something (a menu selection and a typed command, for example), and only one triggers the bug, definitely include that; Why you think it is a bug. What should have happened instead? Whilst this is obvious for some things, (It shouldn't crash when I try to save the file) it is not obvious for others. Give a better way for the program to behave. (If it can't save the file, it should tell me so that I don't keep editing it without realizing I am wasting my effort.); Sometimes screen-shots can help demonstrate bugs. Please do not send one in a Bug Buddy report! But if you have one, mention that you have it, so that a bug-fixer who would like to see it can email you about it; Sometimes a file won't load correctly or at all. You should always include the file with these type of bugs. If you have any suggestions on what caused it or how to fix it, wonderful. If not, don't worry. Just explain what happened. If a developer needs more information, they can mail you back for it. &app; gives you two options. You can Use sendmail directly or Just save to a file so I can submit a bug report manually. If you want to send the bug report to bugzilla then select the option Use sendmail directly. If you want to save the bug report to a file and submit it by yourself you should select the second option. If you want to send a bug report to bugzilla directly then you need to fill out these pieces of information. It makes very good guesses so you should be able to skip straight ahead. Your name Bug Buddy works this out itself, but if you want to change it you can do this here. Email address Please enter a valid email address for you here. This is so developers can request more information from you, or inform you of a fix for your bug. Full path of sendmail This allows you to check that Bug Buddy is looking in the right place when it tries to send email. You will almost certainly not need to change this. Once you have finished your report, you can review the report and decide what to do with it. You will probably want to submit it to the bug tracking system, but if you want to send it elsewhere for some reason you can. You can choose from: Send report If you selected to Use sendmail directly in the previous section you will see the Send report button where the Forward button usually is located. Clicking on Send report will bring up a Question dialog. Clicking on Submit will email the bug report to the bug tracker. Clicking on Cancel will take you back to the Confirmation section. Even though the report should end up at bugzilla, you will see that the address is for bugs.gnome.org. This is fine. Don't change it. It's the staging-post which forwards reports on to bugzilla. If bugzilla has no category for it, then bugs.gnome.org will keep it. Save If you selected to Just save to a file so I can submit the bug report manually in the previous section you will see a Save in text box. Fill in the file where you want the bug report saved to or just click on Browse. If the file already exists, it will ask you whether to overwrite the file or not. Clicking on Save will save the bug report to the file. Bug Buddy will tell you what it has done with your bug report. That's it. Thank you for reporting your bug. Bug Buddy has very few bugs or limitations. Currently known: There is an applet called Tick-A-Stat which can be set to look for core files and timestamp them with their origin and date. Bug Buddy cannot read files which Tick-A-Stat has done this to.