Sample of a training manual for a software tool

Transcription

1 Sampe of a training manua for a software too We use FogBugz for tracking bugs discovered in RAPPID. I wrote this manua as a training too for instructing the programmers and engineers in the use of FogBugz.

2 Tabe of Contents Overview...1 Eements of a good bug report...1 The ife of a bug report...1 The bug report is entered...1 The bug report is assigned to a deveoper The deveoper receives an emai about the bug...2 The bug gets anayzed The bug report is assigned back to the submitter for further detais The bug report is updated with more detais about reproducing the bug The bug gets anayzed again and fixed...2 The bug report gets assigned back to the submitter for approva and cosure Using FogBugz...3 Accessing FogBugz...3 Logging in...3 Entering a new bug...3 Required information...4 Attaching fies...7 Updating the status of a bug...8 Cosing a bug report...8 Associating a bug with a Perforce changeist...8 Fitering bug reports...9 Entering existing bugs into FogBugz...11 Getting Hep...11

3 Overview FogBugz is a bug tracking and project/task management system avaiabe on both Windows and Linux. We are going to use FogBugz to keep track of bugs found in the GUI and in OBE and tasks to be assigned to deveopers, whether they be fixes or new features or capabiities. For now, we wi not be using the project management portion or the wiki. FogBugz uses the term "cases" to refer to bug reports, feature requests, inquiries and schedue items. We are primariy using FogBugz to track bugs and features requests, but this document wi refer to a types of cases as "bug reports" for convenience and famiiarity. We have set up projects which correspond to the different parts of RAPPID such as the modues in OBE, common ibraries, and the GUI. You wi ony see the projects to which you have access. These generay correspond to the permissions you have in Perforce. There are three areas within each project: Documentation Source Test Cases (this area is not avaiabe for the Buid Utiity project) For each bug report, you seect a project and an area into which the bug is categorized. See Entering a new bug on page 3 for more information. Eements of a good bug report When writing your bug reports, incude the foowing three eements: 1. The minima number of steps to reproduce the bug, 2. What you expected to see, and 3. What you saw instead. The ife of a bug report A bug report starts its ife when someone finds something wrong with RAPPID (the GUI or OBE), a test case, or the documentation. The bug report is entered... The person that found the bug (the submitter) enters a bug report in FogBugz, detaiing the bug as described in Eements of a good bug report above. The bug report is assigned to a deveoper... When creating the bug report, the submitter assigns the bug to the deveoper whom they beieve shoud be responsibe for fixing the bug (the resover). Page 1 of 11

4 The deveoper receives an emai about the bug... The assigned deveoper receives an emai in the interna emai system informing them about the bug. The bug gets anayzed... The deveoper anayzes the bug, determining whether it is reay a bug and whether it can be reproduced based on the steps to reproduce it isted by the submitter. See Updating the status of a bug on page 6 for information on what to do if it not reay a bug and other issues. The bug report is assigned back to the submitter for further detais... If it is discovered, for exampe, that there were not enough detais in the bug report to correcty anayze and reproduce the bug, it is assigned back to the submitter expaining the need for more detais. The bug report is updated with more detais about reproducing the bug... The submitter updates the bug and assigns it back to the deveoper. The bug gets anayzed again and fixed... The deveoper can now reproduce the bug and determine the probem. The source code is fixed and checked in using Perforce as usua. The extra step to take is to specify the BugzId on a separate ine in the description in the Perforce changeist. See Associating a bug with a Perforce changeist on page 7 for more information about integration with Perforce. NOTE: Perforce changeists shoud be associated with a FogBugz ID, even if a new feature is being added. This aows us to keep better track of what we have accompished and what we have eft to compete. The deveoper now updates the status of the bug report by cicking the Resove option in the upper right corner of the bug report. See Updating the status of a bug on page 6 for more information. The bug report gets assigned back to the submitter for approva and cosure... The submitter now re-tests the feature in which they found the bug and finds that it has been fixed. They cose the bug report. NOTES: The ony person who shoud cose a bug report is the person who submitted it. FogBugz does not require this, but it is our poicy. FogBugz does not aow you to cose a bug report that is Active. You must resove a bug report before it can be cosed. As a deveoper, work through bugs assigned to you in order of priority as assigned in the bug reports. Page 2 of 11

5 Using FogBugz Accessing FogBugz You access FogBugz using a web browser. The foowing address was added to the Favorites menu in Internet Exporer in Windows and to the Bookmarks toobar in Mozia in Linux: NOTE: When accessing FogBugz in Linux, be sure to use the Mozia web browser, NOT Konquerer. FogBugz does not dispay correcty in Konquerer. Logging in Everyone has an account in FogBugz that you og into using your interna emai and the same password you use to og into your Windows and Linux accounts on the deveopment network. Your emai address is <your username>@rsr.com. For exampe, michaea@rsr.com. Log in using the fieds on the right side of the initia page of FogBugz. Figure 1: Logging on to FogBugz Entering a new bug Bugs are entered as "cases." To enter a new bug in FogBugz once you have ogged in, cick the New Case option on the toobar. NOTE: Do not enter a new case from the initia ogin page. Make sure to og in first. The New Case page dispays. Page 3 of 11

6 Figure 2: Entering a new bug Required information Specify the information indicated beow. Note that not a fieds are currenty used when entering bugs. Fied Purpose Project Seect the project corresponding to the where you found the bug, e.g., goba or engineering common services, an OBE modue, the GUI (GUI - Main). Area Indicate whether the bug seems to occur in the way the program operates (Source), due to the vaues in a test case (Test Cases), or an error in the Documentation. If there is an error in one or more test cases, indicate the fiename(s) for the test case(s) in the testcases directory, or the project name and case name(s) of the test case(s) in the GUI. Page 4 of 11

7 Fied Category Purpose Seect the category for the report. Bug: Use this option to indicate a probem with in the RAPPID software, a test case or documentation. Feature: Use this option to specify a new feature, test case, or section of documentation to be added to the indicated portion of RAPPID. Inquiry: Use this option to submit questions about the software, test cases, or documentation. Schedue Item: Use this option to request a meeting, to schedue a code review, or for other items to be schedued. Assigned To Seect the person who is responsibe for fixing the bug. If you are not sure to who to assign the bug, assign it to the Administrator, who wi assign it to the correct person. Priority Seect the priority of the bug depending on its severity and how seriousy it affects the operation of RAPPID. Version For the version, enter the date the executabe or ibrary containing the probem was fetched or buit. [Revision number?] Status When initiay submitting a bug, the Status is automaticay set to Active. Change the status after examining a bug that has been assigned to you. See Updating the status of a bug on page 6 for more information about options avaiabe when updating the status of a bug. Main description box Enter a description of the bug, making sure to incude the steps to reproduce the bug, the expected behavior, and the actua behavior. Attach a fie If a screenshot heps describe the bug or a text fie with resuts or more information, you can attach one or more fies to the bug report. See Attaching fies on page 6 for more detais. When you are done inputting information about the bug into FogBugz, cick OK beow the main description box to submit the bug report. The ID of the bug report dispays in the upper eft corner of the submitted bug report. Page 5 of 11

8 Figure 3: The ID (10) of the bug report in the upper eft corner Attaching fies To attach a screenshot, a text fie, a Word fie, or any other fie that heps to describe or provide more information about the bug, cick the Attach a fie ink on the bug report. The Choose fie diaog box dispays. Navigate to the fie you want to attach, seect it, and cick Open. The fie is isted at the bottom of the bug report. NOTE: If you need hep creating screenshots in Windows and/or Linux, ask Lori for hep. If you attach a graphic fie, such as a.png fie, the graphic dispays in the bug report when it is submitted. NOTE: The maximum aowed attachment size is 100 MB. However, you shoud NEVER attach arge fies. Instead, provide the path where the fie(s) can be found. Updating the status of a bug The status of a bug report shoud be kept updated at a times. For exampe, as a deveoper, when you fix a bug, determine it is not reproducibe or it is there by design, etc., cick Resove in the upper right corner of the bug report. The bug report opens in edit mode and you have six options for updating the status: Resoved (Fixed): Seect this option if you have fixed the bug and checked the fixed code into Perforce, incuding the FogBugz ID in the description within the changeist. Page 6 of 11

9 Resoved (Not Reproducibe): Seect this option if you cannot reproduce the bug as described by the submitter. If you choose this option, Assign it back to the submitter expaining that you need more detais about steps to reproduce the bug. Resoved (Dupicate): Seect this option if you have discovered that this bug report is the dupicate of another bug report aready in FogBugz. Resoved (Postponed): Do not use this option. Resoved (Won't fix): Do not use this option. Resoved (By Design): Seect this option if the bug is not reay a bug at a, but works that way intentionay. In a cases, the bug report needs to be assigned back to the submitter at this stage. Cosing a bug report If you have submitted a bug report in FogBugz, you are responsibe for testing it when it is resoved in some manner and assigned back to you and cosing it when appicabe. If a bug report is ready to be cosed, as the submitter, cick Cose in the upper right corner of the bug report. Enter a description as appicabe and cick OK. You might aso, as the submitter, change the status to one of the Resoved options and cose the bug report at the same time by cicking Resove in the upper right corner of the bug report, entering a description, and cicking the Resove & Cose button. Associating a bug with a Perforce changeist As a deveoper, when you fix a bug, you have checked out fies in Perforce to change and checked them in when the bug is fixed. In the changeist's description, when checking in the fies, specify on a separate ine in the description the FogBugz ID with which the changeist is associated. The foowing is an exampe of the format to use: BugzId: 10 NOTE: Every changeist you check in to Perforce shoud be associated with a bug report or a feature request in FogBugz. Fitering bug reports When you og into FogBugz, bug reports are isted according to the current fitering criteria seected. Cick Fiter to drop down a ist of the fiters avaiabe. Cick the pus sign next to a fiter to view the options avaiabe. Page 7 of 11

10 Figure 4: Cicking Fiter to view avaiabe fiters Seect an option to appy that fiter to your ist of bug reports. If you want to remove a fiter criteria you have previousy appied, cick the name of the fiter criteria you want to remove and seect the option avaiabe that wi dispay a bug reports that match that criteria. For exampe, if you had seected to view a open cases and now you want to see a cases, whether they are open or cosed, cick open and seect A from the drop-down ist that dispays. Page 8 of 11

11 Figure 5: Removing a fiter criteria You can save fiters so you can quicky change how your ist of bug reports is dispayed. Once you have set up a fiter with a the criteria you want, cick the Save button in the upper right corner of the screen Figure 6: Saving a fiter above the ist of bug reports. Type a name for the fiter in the edit box and cick OK. The name of the fiter now dispays where "Fiter" dispayed previousy. Entering existing bugs into FogBugz Over time, you may have coected misceaneous notes about bugs you have found, features to be added to a code at a ater date, etc. These shoud be entered into FogBugz, but do not spend a ot of time doing so. Enter them over time, so as not to severey interrupt your current tasks. Page 9 of 11

12 Getting Hep For more information about using FogBugz, cick the Hep ink in the upper right corner of the FogBugz screen. Figure 7: Accessing hep within FogBugz Page 10 of 11