Bug Triage Guidelines
Triaging of bugs is an important task; when done correctly, it can reduce the time between reporting a bug and the availability of a fix enormously.
Triager should focus on new bugs, and try to define the problem easily understandable and as accurate as possible. The goal of the triagers is to reduce the time that developers need to solve the bug report.
A triager is like an assistant that helps with the information gathering and possibly the debugging of a new bug report. Because a triager helps preparing a bug before a developer gets involved, it can be a very nice role for new community members that are interested in technical aspects of the software.
Triagers will stumble upon many different kind of issues, ranging from reports about spelling mistakes, or unclear log messages to memory leaks causing crashes or performance issues in environments with several hundred storage servers.
Nobody expects that triagers can prepare all bug reports. Therefore most developers will be able to assist the triagers, answer questions and suggest approaches to debug and data to gather. Over time, triagers get more experienced and will rely less on developers.
Bug triage can be summarized as below points:
- Is there enough information in the bug description?
- Is it a duplicate bug?
- Is it assigned to correct component of GlusterFS?
- Are the Bugzilla fields correct?
- Is the bug summary is correct?
- Assigning bugs or Adding people to the "CC" list
- Fix the Severity And Priority.
- Todo, If the bug present in multiple GlusterFS versions.
- Add appropriate Keywords to bug.
The detailed discussion about the above points are below.
Getting Started: Find reports to triage
There are many different techniques and approaches to find reports to triage. One easy way is to use these pre-defined Bugzilla reports (a report is completely structured in the URL and can manually be modified):
- New bugs that do not have the 'Triaged' keyword Bugzilla link
- New features that do not have the 'Triaged' keyword (identified by FutureFeature keyword, probably of interest only to project leaders) Bugzilla link
- New glusterd bugs
- New Replication(afr) bugs
- New bugs against version 3.8
New bugs against mainline (development branch)
- Untriaged FreeBSD bugs
- Untriaged Mac OS bugs
In addition to manually checking Bugzilla for bugs to triage, it is also possible to receive emails when new bugs are filed or existing bugs get updated.
Each week, on the Monday, an email is sent to gluster-devel about new bugs which are yet to be triaged.
If at any point you feel like you do not know what to do with a certain report, please first ask irc or mailing lists before changing something.
Is there enough information?
To make a report useful, the same rules apply as for bug reporting guidelines.
It's hard to generalize what makes a good report. For "average" reporters is definitely often helpful to have good steps to reproduce, GlusterFS software version , and information about the test/production environment, Linux/GNU distribution.
If the reporter is a developer, steps to reproduce can sometimes be omitted as context is obvious. However, this can create a problem for contributors that need to find their way, hence it is strongly advised to list the steps to reproduce an issue.
There should be only one issue per report. Try not to mix related or similar looking bugs per report.
It should be possible to call the described problem fixed at some point. "Improve the documentation" or "It runs slow" could never be called fixed, while "Documentation should cover the topic Embedding" or "The page at http://en.wikipedia.org/wiki/Example should load in less than five seconds" would have a criterion. A good summary of the bug will also help others in finding existing bugs and prevent filing of duplicates.
If the bug is a graphical problem, you may want to ask for a screenshot to attach to the bug report. Make sure to ask that the screenshot should not contain any confidential information.
Is it a duplicate?
Some reports in Bugzilla have already been reported before so you can search for an already existing report. We do not recommend to spend too much time on it; if a bug is filed twice, someone else will mark it as a duplicate later. If the bug is a duplicate, mark it as a duplicate in the resolution box below the comment field by setting the CLOSED DUPLICATE status, and shortly explain your action in a comment for the reporter. When marking a bug as a duplicate, it is required to reference the original bug.
If you think that you have found a duplicate but you are not totally sure, just add a comment like "This bug looks related to bug XXXXX" (and replace XXXXX by the bug number) so somebody else can take a look and help judging.
The webui for bug triage gathers a list of bugs every night. This website can be used to identify duplicates relatively easily.
Is it assigned to correct component of GlusterFS?
Make sure the bug is assigned on right component. Below are the list of GlusterFs components in bugzilla.
- access control - Access control translator
- BDB - Berkeley DB backend storage
- booster - LD_PRELOAD'able access client
- build - Compiler, package management and platform specific warnings and errors
- cli -gluster command line
- core - Core features of the filesystem
- distribute - Distribute translator (previously DHT)
- errorgen - Error Gen Translator
- fuse -mount/fuse translator and patched fuse library
- georeplication - Gluster Geo-Replication
- glusterd - Management daemon
- HDFS - Hadoop application support over GlusterFS
- ib-verbs - Infiniband verbs transport
- io-cache - IO buffer caching translator
- io-threads - IO threads performance translator
- libglusterfsclient- API interface to access glusterfs volumes programatically
- locks - POSIX and internal locks
- logging - Centralized logging, log messages, log rotation etc
- nfs- NFS component in GlusterFS
- nufa- Non-Uniform Filesystem Scheduler Translator
- object-storage - Object Storage
- porting - Porting GlusterFS to different operating systems and platforms
- posix - POSIX (API) based backend storage
- protocol -Client and Server protocol translators
- quick-read- Quick Read Translator
- quota - Volume & Directory quota translator
- rdma- RDMA transport
- read-ahead - Read ahead (file) performance translator
- replicate- Replication translator (previously AFR)
- rpc - RPC Layer
- scripts - Build scripts, mount scripts, etc.
- stat-prefetch - Stat prefetch translator
- stripe - Striping (RAID-0) cluster translator
- trace- Trace translator
- transport - Socket (IPv4, IPv6, unix, ib-sdp) and generic transport code
- unclassified - Unclassified - to be reclassified as other components
- unify - Unify translator and schedulers
- write-behind- Write behind performance translator
- libgfapi - APIs for GlusterFS
- tests- GlusterFS Test Framework
- gluster-hadoop - Hadoop support on GlusterFS
- gluster-hadoop-install - Automated Gluster volume configuration for Hadoop Environments
- gluster-smb - gluster smb
- puppet-gluster - A puppet module for GlusterFS
Tips for searching:
- As it is often hard for reporters to find the right place (product and component) where to file a report, also search for duplicates outside same product and component of the bug report you are triaging.
- Use common words and try several times with different combinations, as 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.
- Drop the ending of a verb (e.g. search for "delet" so you get reports for both "delete" and "deleting"), and also try similar words (e.g. search both for "delet" and "remov").
- Search using the date range delimiter: Most of the bug reports are recent, so you can try to increase the search speed using date delimiters by going to "Search by Change History" on the search page. Example: search from "2011-01-01" or "-730d" (to cover the last two years) to "Now".
Are the fields correct?
Sometimes the summary does not summarize the bug itself well. You may want to update the bug summary to make the report distinguishable. A good title may contain:
- A brief explanation of the root cause (if it was found)
- Some of the symptoms people are experiencing
Adding people to the "CC" or changing the "Assigned to" field
Normally, developers and potential assignees of an area are already CC'ed by default, but sometimes reports describe general issues or are filed against common bugzilla products. Only if you know developers who work in the area covered by the bug report, and if you know that these developers accept getting CCed or assigned to certain reports, you can add that person to the CC field or even assign the bug report to her/him.
To get an idea who works in which area, check To know component owners , you can check the "MAINTAINERS" file in root of glusterfs code directory or querying changes in Gerrit (see Simplified dev workflow)
Severity And Priority
Please see below for information on the available values and their meanings.
This field is a pull-down of the external weighting of the bug report's importance and can have the following values:
|urgent||catastrophic issues which severely impact the mission-critical operations of an organization. This may mean that the operational servers, development systems or customer applications are down or not functioning and no procedural workaround exists.|
|high||high-impact issues in which the customer's operation is disrupted, but there is some capacity to produce|
|medium||partial non-critical functionality loss, or issues which impair some operations but allow the customer to perform their critical tasks. This may be a minor issue with limited loss or no loss of functionality and limited impact to the customer's functionality|
|low||general usage questions, recommendations for product enhancement, or development work|
|unspecified||importance not specified|
This field is a pull-down of the internal weighting of the bug report's importance and can have the following values:
|low||not very important|
|unspecified||importance not specified|
Bugs present in multiple Versions
During triaging you might come across a particular bug which is present across multiple version of GlusterFS. Here are the course of actions:
- We should have separate bugs for each release (We should clone bugs if required)
- Bugs in released versions should be depended on bug for mainline
(master branch) if the bug is applicable for mainline.
- This will make sure that the fix would get merged in master branch first then the fix can get ported to other stable releases.
Note: When a bug depends on other bugs, that means the bug cannot be fixed unless other bugs are fixed (depends on), or this bug stops other bugs being fixed (blocks)
Here are some examples:
A bug is raised for GlusterFS 3.5 and the same issue is present in mainline (master branch) and GlusterFS 3.6
- Clone the original bug for mainline.
- Clone another for 3.6.
- And have the GlusterFS 3.6 bug and GlusterFS 3.5 bug 'depend on' the 'mainline' bug
A bug is already present for mainline, and the same issue is seen in GlusterFS 3.5.
- Clone the original bug for GlusterFS 3.5.
- And have the cloned bug (for 3.5) 'depend on' the 'mainline' bug.
Many predefined searches for Bugzilla include keywords. One example are the searches for the triaging. If the bug is 'NEW' and 'Triaged' is no set, you (as a triager) can pick it and use this page to triage it. When the bug is 'NEW' and 'Triaged' is in the list of keyword, the bug is ready to be picked up by a developer.
Triaged : Once you are done with triage add the Triaged keyword to the bug, so that others will know the triaged state of the bug. The predefined search at the top of this page will then not list the Triaged bug anymore. Instead, the bug should have moved to this list.
EasyFix : By adding the EasyFix keyword, the bug gets added to the list of bugs that should be simple to fix. Adding this keyword is encouraged for simple and well defined bugs or feature enhancements.
Patch : When a patch for the problem has been attached or included inline, add the Patch keyword so that it is clear that some preparation for the development has been done already. If course, it would have been nicer if the patch was sent to Gerrit for review, but not everyone is ready to pass the Gerrit hurdle when they report a bug.
You can also add the Patch keyword when a bug has been fixed in mainline and the patch(es) has been identified. Add a link to the Gerrit change(s) so that backporting to a stable release is made simpler.
Documentation : Add the Documentation keyword when a bug has been reported for the documentation. This helps editors and writers in finding the bugs that they can resolve.
Tracking : This keyword is used for bugs which are used to track other bugs for a particular release. For example 3.6 tracker bug
FutureFeature : This keyword is used for bugs which are used to request for a feature enhancement ( RFE - Requested Feature Enhancement) for future releases of GlusterFS. If you open a bug by requesting a feature which you would like to see in next versions of GlusterFS please report with this keyword.
Add yourself to the CC list
By adding yourself to the CC list of bug reports that you change, you will receive followup emails with all comments and changes by anybody on that individual report. This helps learning what further investigations others make. You can change the settings in Bugzilla on which actions you want to receive mail.
Bugs For Group Triage
If you come across a bug/ bugs or If you think any bug should to go thorough the bug triage group, please set NEEDINFO for email@example.com on the bug.
Resolving bug reports
See the Bug report life cycle for the meaning of the bug status and resolutions.
Example of Triaged Bugs
This Bugzilla filter will list NEW, Triaged Bugs