What Is Bugzilla?
Bugzilla is an issue tracking database. The LSB project uses this tool to let people report bugs and request features, and assigns these bugs to the appropriate developers. Developers can use Bugzilla to keep a to-do list as well as to prioritize, schedule and track dependencies.
Not all 'bugs' are bugs. Some items in the database are known as Requests For Enhancement (RFE). An RFE is a bug whose severity field is set to 'enhancement'. People often say 'bug' when they mean 'item in Bugzilla', so RFEs often wind up being called bugs.
Enter the tasks you're planning to work on as enhancement requests and Bugzilla will help you track them and allow others to see what you plan to work on. If people can see your flight plan, they can avoid duplicating your work and can possibly help out or offer feedback.
Most significant work should have a bug. Bugs are the audit trail for work done towards a release, and the primary means of generating release notes and other information about what was changed/added. Version control logs of course provide information also, but are not as useful since a single conceptual change may be spread across many components, and are harder to track unless there's a bugzilla entry to unify them.
The LSB project manages releases through special tracking bugs called "rollup" bugs, these bugs are set to be blocked by all the issues that must be resolved before a release can be made.
Anatomy of an LSB Bug
Bugs and RFEs are composed of many fields. Some of them are described here.
- The LSB has a few shippable products, each of which has a category in the Bugzilla. There are also some categories that are not really products, such as Infrastructure or Website; nonetheless the top-level container in Bugzilla is the Product so these are also classified as Products. The LSB has a particular complication in that there's a lot of cross-pollination between Products: a problem may require a database fix, and affect the spec, tests, and build tools. There is no hard policy on whether this should be filed as one or multiple bugs. A guideline might be if a single fix is likely to take care of multiple products in one go, a single bug is okay, but affected products should be noted as instructions to verifiers. In this situation, the specification should probably be considered the "master" category. If large chunks of discrete work is required on different products, multiple cross-referenced bugs may be better. If you're not sure, file one (and note the issue) and leave it up to triage to decide the next step.
- Each Product is divided into categories, which may be portions of the shippable product, a generic container (often All), or something else. Try to pick the right Product and Component to most accurately categorize your bug, but don't worry if you're not sure which one to use, bug triage will fix it up if necessary.
- If the bug is architecture-specific, use the Platform field to indicate this. This information should also be duplicated in the bug Description and perhaps the Summary - as a third-level field Platform may not always be looked at (often left out of custom views to keep things on one screen-width). In some cases a Component is split into two: -generic and -archspecific. If picking the latter, Platform must be used to fully categorize the bug. If it applies to multiple architectures, but not all, just pick one applicable value for Platform and list the rest in the bug text.
- This field is used to store various keywords. The LSB does not use this field intensively, but a few keywords are defined to make for easier searches: backport (bug against one release, backport candidate for the previous release), FHS (FHS bugs/enhancements), helpwanted (need someone else to pitch in on this bug, perhaps to test), ISO (issues specifically from the ISO ballot for DIS 23360), rollup (bugs which are specifically dependency tracker bugs - see next item). For specification bugs, it is also recommended to use a keyword to indicate that, as progressing the bug may cause the category to be changed. Release notes are generally written against bugs fixed for the specification, so to still find them after the category changes, use spec31 for the 3.1 release, spec40 for the 4.0 release, etc.
- If a bug can't be fixed until another bug is fixed, that's a dependency. For any bug, you can list the bugs it depends on and bugs that depend on it. Bugzilla can display a dependency graph which shows which the bugs it depends on and are dependent on it. The LSB project uses dependencies to track releases by using "rollup" bugs to make the release depend on all of the mustfix bugs for the product. Those bugs can't be marked Resolved-Fixed until the dependencies are Resolved-Fixed.
- Add attachments to a bug where it makes sense. Please submit patches as attachments to bugs rather than inline in the bug or using email. Screenshots, error logs, and other descriptive information can also be attached, especially if pasting the text inline would make it harder to read than using an attachment (e.g. line wrapping can make inline pastings unreadable). Note you need to create the bug first, then as a separate step add the attachment. Never simply attach a patched source file ... someone else may edit the offending file while this bug is being reviewed, and that makes it much harder for a reviewer to see what changed.
Life Cycle of an LSB Bug
- Bugs submitted to the LSB Bugzilla by default go straight into the NEW state (UNCONFIRMED is not used). Unless otherwise set at submission time, it will get the default owner for that product. The owner may not be the eventual developer who will work on it. Bug triage may cause the owner to be reassigned, or someone may simply take it. If the bug remains new and inactive for more than a week, Bugzilla nags the bug's owner with email until action is taken (Note: nagging seems to be off at present). Whenever a bug is reassigned or has its component changed, its status is set back to NEW. The NEW status means that the bug is newly added to a particular developer's plate, not that the bug is newly reported - this gives the developer a chance to either Accept the bug or disagree with the assignment by assigning it to someone else, possibly back to the product owner.
- Some developers make up the bug triage team. This team meets periodically (usually in irc) and provides a disposition of bugs that haven't gotten attention. The idea is not to try to resolve the bug, but to limit the discussion to who should this be given to, is the priority right, is the category right, which milestone should this be addressed in, and should it be added to a particular release blocker. As part of this process the bug is often flipped to ASSIGNED state. The bug will also change to this state if the person it is assigned to chooses to accept it, which may well happen outside a triage meeting.
- By the way, whenever you change a field in a bug it's a good idea to add additional comments to explain what you are doing and why. Make a note whenever you do things like change the component, reassign the bug, create an attachment, add a dependency or add someone to the CC list. Whenever someone makes a change to the bug or adds a comment, the owner, reporter and the the CC are sent an email (unless they have switched it off) showing the changes to the bug report. The LSB Bugzilla is configured to require a comment for most changes.
- There are two ways that a bug typically gets resolved:
- * Simple bugs - you work on the offending source material in a local branch, find the problem and fix it. Build and test the affected module. If you are convinced that this is the correct fix without further review, check in your change with the bug number noted in the commit message, and push the change up to the master branch. Describe your changes in the bug while marking it RESOLVED-FIXED.
- * More complex bugs - as before, work on the source code until you believe that you have addressed the problem. At that point, generate a patch - bzr will do this easily for you with "bzr diff", and attach the patch to the bug (see "Attachments" above). Add any appropriate reviewers to the bug's "Cc list". Leave the bug Open (assigned to you) until others have had a chance to review your patch. Only commit the patched code to bzr and mark the bug RESOLVED-FIXED after this review has taken place. Note that other people may have updated the same source while the bug was in review (or even before it got to review), so you'll have to check if there are changes and perform a merge if so.
- For bugs which affect multiple categories, if someone else has to work on some other category, the bug should be reassigned after your piece is complete.
- The LSB project has not used the bugzilla voting feature, if someone can suggest how that would be beneficial, we'll consider it.
- When work on a bug is complete it's marked RESOLVED and given one of the following resolutions:
- A fix for this bug has been checked into the cvs tree and tested by the person marking it FIXED.
- The problem described is not a bug.
- The problem described is a bug which will never be fixed, or a problem report which is a "feature", not a bug.
- The problem is a duplicate of an existing bug. Marking a bug duplicate requires the bug number of the duplicating bug and will add a comment with the bug number into the description field of the bug it is a duplicate of. A pair of bugs on the same issue often has useful - and different - information in both, so make sure to copy over any relevant extra notes from the bug being closed to the one left open.
- All attempts at reproducing this bug in the current build were futile. If more information appears later, please re-open the bug, but for now it's not being looked at.
- The process of making sure a bug is completely and correctly fixed is not a precise science. The LSB uses automated builds via a tool called buildbot (periodic and on code changes) which help provide a continuous integration service. Part of verifying is waiting until the autobuilds complete and checking that everything went okay, then making sure that the affected packages install and work correctly. Unfortunately this is only part of the problem, you didn't break the builds, but maybe the fix is incomplete and misses some cases. There's no formal way to check that unless a test can be developed for the feature. So in practice LSB relies on the model of letting affected users complain if the fix doesn't work right for them.
- Some bugs will not exactly fit the model described, if they don't belong to something which is autobuilt for example, Use common sense. A requested change to web content is both "checked in" and "released" when it's pushed, so here the bug could be set to CLOSED with a comment "checked on live website. Verified - closing".
- When the product containing the fix ships, the bug can be marked CLOSED. This is best tracked by using the rollup/release blocker method. If bug 10 is the rollup for "Release 1.0 of the SDK", and bug 20 is a fix to a header file that should appear in that release, then bug 20 should block bug 10. Once Release 1.0 ships, it's easy to see which bugs blocked it, and all those bugs, which should be in VERIFIED state (or we shouldn't actually be making the release!), can be flipped to CLOSED state.
- Sometimes a bug moves into a state that indicates completion of work, and it turns out it's not done, or wrong - in this case mark it REOPENED. The assigned will be notified, and the cycle starts over.
There are two more states that represent interim stages, essentially meaning there's a pause in the workflow until some feedback can be received.
- A developer is prepared to work on the bug but does not have enough details to proceed, and is asking for more details (usually from the submitter)
- A developer may have a fix available, but is not able to test it completely, or is not able to reproduce the environment in which the problem occurs, and so would like someone else (usually the submitter) to try it out.
Be careful when changing the status of someone else's bugs. Instead of making the change yourself, you may wish to make a note of your proposed change as a comment and let the bug's owner review this and make the change themselves. For instance, if you think one bug is a duplicate of another, make a note of it in the 'Additional Comments' section.
[wiki:UsingLsbBugzilla/Comments User Comments]