View source for Bugsquad/Quick Introduction to Bugzilla

Bugzilla is the bug tracking software the KDE community uses to handle the bug reports of their applications.

Our bugtracker is located at [https://bugs.kde.org https://bugs.kde.org]

Main screen of the bugtracker (default style):

[[File:Bugzilla_guide_Intro.png]]

==Fields of a bug report==

[[File:Bugzilla_guide_bugreportmain.png]]

'''Summary:''' Brief description of the bug

'''Product:''' Application or library which is being affected by the bug

'''Component:''' Specific component inside the product which is being affected by the bug

'''Version:''' Version of the application or library which shows the bug (Note: different products could have different policies about this field: it could represent the last version in which the bug is present, or the first version in which the bug appeared). This field defaults to "unspecified".

'''Priority:''' Priority of the bug report. It defaults to "NOR"(normal) and ''it must not be changed''.

'''Severity:''' Type of bug:
* "Crash": a bug that causes the application to close itself or freeze/hang
* "Normal": a non-crash bug report (misbehavior)
* "Minor": a non-crash bug which is not really important (a little detail)
* "Wishlist": a feature request

'''Status:''' Status of the bug report:
* "UNCONFIRMED": the issue was not confirmed by other bug reporters or developers
* "NEW": the issue was confirmed by other bug reporters or contributors
* "ASSIGNED": a developer/user is working to fix it
* "NEEDSINFO": the issue was closed because it is lacking information
* "RESOLVED": the issue was closed because of different motives:
** "FIXED": the bug was fixed by developers/contributors
** "WORKSFORME": the bug cannot be reproduced and it is considered fixed
** "WONTFIX": the bug is not going to be fixed (developers policy)
** "UPSTREAM/DOWNSTREAM": the bug was not related to KDE (problems related to installation and distributions or to external libraries or plugins)
** "INVALID": the described issue was not a real bug (intended behavior or installation problems)
** "DUPLICATE": the bug was already reported

'''Votes:''' Current number of votes the bug report has. Votes can be useful to confirm a bug (status changes from UNCONFIRMED to NEW).

'''Comments:''' The first comment is always the original description of the bug sent by the reporter. The other ones could be comments added by the same reporter or by any other user, a bug triager, or a developer.

'''Keywords:''' Special words which are used to mark special reports, in order to find them easily. ''Several keywords can be used separated by commas.''

'''CC List:''' List of mail addresses (from reporters or contributors) who are tracking the bug report and who are going to get a mail notification about every change on it.

More information about bug report's life cycle and other fields can be found at [https://bugs.kde.org/page.cgi?id=fields.html https://bugs.kde.org/page.cgi?id=fields.html]

==Common Operations==

===Configure your account (Important)===

Prior to start using your bugzilla account, it is important to configure it.

You can access your control panel using the "Edit my Preferences" link or with this URL: [https://bugs.kde.org/userprefs.cgi User Preferences]

[[File:Bugzilla_guide_preferences.png]]

* There is an '''important setting which must be changed''' to avoid confusions on some situations: ''"After changing a bug" should be set to "Show the updated bug"''

With the default behavior, after you modify a bug report (or after adding a comment) you will be redirected to another bug report (the next in your search list). Most of the users get confused with this behavior and write other comment in that bug report, thinking it is the same as before.

===Get a description of the products and components===

You can properly identify each KDE application with its bugzilla product component using this feature: [https://bugs.kde.org/describecomponents.cgi Describe components]

===Searching bug reports===

====Simple Search====

The simple search provides a quick way to look for bug reports without the need to specify too much specific fields filters.

[https://bugs.kde.org/query.cgi?format=specific Simple Search URL]

[[File:Bugzilla_guide_simplesearch.png‎]]

In the '''Status''' field you can select:
* Open: bug reports which are currently active, unfixed or untested
* Closed: bug reports which are not active, fixed, invalid, unreproducible
* All: both open and closed bug reports

In the '''Product''' field you select the main application or library suffering the bug

In the '''Words''' field you can enter some keywords which will be used to identify the bug report (it will search trying to match those words with the Summary of the report)
You can use ''keywords'' or a ''complete phrase''
You can also leave this field empty to look for all the bug reports

=====Example=====
Search for currently active Plasma bug reports about icons being misplaced on login.
 * Status: "Open"
 * Product: "Plasma"
 * Words: "icon move login" or "icons are randomly moved during the startup"

====Advanced Search====

This kind of search allows the user to filter a lot of fields using several combinations.

[https://bugs.kde.org/query.cgi?format=advanced Advanced Search URL]

[[File:Bugzilla_guide_advancedsearch.png‎]]

The important field in this form are:
* '''Summary''': words to match on the summary of the bug report (it could be "all the words" or "any word"). You can leave this field empty to not filter the summary (shows all the reports)
* '''Product''' and '''Component''' to filter the main application/library and component suffering the bug (the Component field defaults to "general")
* '''A Comment''': words to match on the full description (or comments) of the bug report (it could be "all the words" or "any word"). This field is really useful as the full description will have more information than a Summary. You can leave this field empty to not filter the comments (shows all the reports)
* '''Status'''. This field defaults to the "Opened" statuses.
* '''Severity''' to filter the type of bug

You can setup a '''date delimiter''' using the "Bug Changes" group: you can set two dates and select a field to compare: "Bug creation", "Last modification", and so on.
The dates' format can be "YYYY-MM-DD", "Xd" (X days), "Xm" (X months), "Now" (Today)

You can filter reports which are assigned or have comments of a '''specific user''' using the "Email address, bug number and votes" group.

You can also select the '''sort method''' to use: by bug number, by importance, by last order used.

Fields which could remain untouched (as they are not really useful to filter out. And we don't use some of them):
"Target", "The URL", "Keywords", "Priority", "Hardware", "OS"

=====Example=====

Search for bugs in the folderview widget (Plasma-desktop) related to the preview of images not working on a network share, currently opened and confirmed:

 * Summary: "preview fail" or "preview not working"
 * Product: "plasma"
 * Component: "widget-folderview"
 * A Comment: "network" or "network share" or "remote"
 * Status: "NEW", "ASSIGNED" and "REOPENED"
 * Severity: "minor" and "normal" (it is not a crash and it is not a major bug)

====Search Results====

[[File:Bugzilla_guide_listreports.png‎ ]]

With the default style you can easily recognize the different type of bug reports by colors (red are crashes, yellow are normal reports and green are feature requests)

* To access any bug report listed you need to click its ''report ID''
* You can customize the columns you want to show for each bug report in the list using the option ''"Change Columns"'' below.

====Searching Hints====

* '''Use common words and try several times with different combinations''': as bug reports are written by humans (most of the times), there could be several ways to describe the same problem. If you choose the proper and common words, and you try several times with different combinations of those, you ensure to have matching results.

* D'''o not use too much filters the first time you look for something''': If you do it, you may lose some valuable results which could be related to your search. Increase the level of filtering once you have a lot of results, to try to increase the accuracy.

* '''Search using date range delimiter''': most of the bug reports are recent, so you can try to increase the search speed using date delimiters. Example: search from "2009-01-01" to "Now", if you don't find results, search from "2008-01-01" to "2009-01-01". This way you reduce the bugzilla server load.

===Adding comments===

In every bug report page, you will find a textbox (below the comments) which allows you to add a comment to that report

[[File:Bugzilla_guide_addcomment.png‎]]

In this textbox you can describe your discovery: you can(not) reproduce the bug; you can provide more information or details. You can also request more information from the reporter

* If the ''"Add Your Name <your@mail.com> to CC list"'' checkbox is enabled, you will be able to track this bug report and get notifications if some field changes or if a new comment is added (useful to keep track of the reporter feedback)

When you are ready, click the '''Commit''' button

===Modifying a bug report (permissions required)===

If you have the enough bugzilla permissions, you can modify more fields of a bug reports. This is oftenly useful while organizing ("triaging") the reports.

[[File:Bugzilla_guide_edit1.png]]

You can:
* Update the bug report's Summary (to provide a better general description)
* Set an alias (to identify this bug report quickly using a word instead of a bug report ID)
* Move the bug report to a different product or component (useful if a bug reported against an application is known to be a problem in a general library; or if the report was assigned to the wrong product)
* Customize the version, severity and priority fields.

[[File:Bugzilla_guide_edit2.png]]

Then you can:
* Update the Platform and Operating System field (as those fields are not oftenly completed, but they are useful to filter the search results)
* Modify the person assigned to that bug report ('''Note:''' this should only be changed when reassigning a bug report from a product to a different one)
* Add or remove people to the CC list (so they will receive notifications of that bug report)

[[File:Bugzilla_guide_edit3.png]]

Finally you can modify the bug report status:
* Mark it as confirmed (NEW)
* Mark it as fixed or non-reproducible (RESOLVED as FIXED or RESOLVED as WORKSFORME)
* Mark it as duplicate of another bug report (DUPLICATE of bug report XXXXXX)
* Mark it as waiting for information/feedback (NEEDSINFO, WAITINGFORINFO)
* Reopen it (currently closed bug report marked again as UNCONFIRMED or REOPENED)

==General Tips==

* Take your time to discover bugzilla and its options.
* Customize your settings until you feel confortable working with the bug tracker and tools
* Bookmark the webpages of the common operations you use
* Generate custom searches and save it to look at them later
* Do not try to do too much things at the same time or you will end up with a headache :)