diff options
Diffstat (limited to 'doc/developer-guide/Bug-Triage.md')
| -rw-r--r-- | doc/developer-guide/Bug-Triage.md | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/doc/developer-guide/Bug-Triage.md b/doc/developer-guide/Bug-Triage.md new file mode 100644 index 00000000000..bcd475e81fb --- /dev/null +++ b/doc/developer-guide/Bug-Triage.md @@ -0,0 +1,400 @@ +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 summarised 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. + +Weekly meeting about Bug Triaging +--------------------------------- + +We try to meet every week in \#gluster-meeting on Freenode. The meeting +date and time for the next meeting is normally updated in the +[agenda](https://public.pad.fsfe.org/p/gluster-bug-triage). + +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](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&f1=keywords&keywords=Triaged%2CFutureFeature&keywords_type=nowords&list_id=3014117&o1=nowords&product=GlusterFS&query_format=advanced&v1=Triaged) +- New **features** that do not have the 'Triaged' keyword (identified + by FutureFeature keyword, probably of interest only to project + leaders) [Bugzilla + link](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&f1=keywords&f2=keywords&list_id=3014699&o1=nowords&o2=allwords&product=GlusterFS&query_format=advanced&v1=Triaged&v2=FutureFeature) +- New glusterd bugs: [Bugzilla + link](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&product=GlusterFS&f1=keywords&o1=nowords&v1=Triaged&component=glusterd) +- New Replication(afr) bugs: [Bugzilla + link](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&component=replicate&f1=keywords&list_id=2816133&o1=nowords&product=GlusterFS&query_format=advanced&v1=Triaged) +- New distribute(DHT) bugs: [Bugzilla + links](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&component=distribute&f1=keywords&list_id=2816148&o1=nowords&product=GlusterFS&query_format=advanced&v1=Triaged) + +- New bugs against version 3.6: + [<https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&product=GlusterFS&f1=keywords&f2=version&o1=nowords&o2=regexp&v1=Triaged&v2>=\^3.6 + Bugzilla link] +- New bugs against version 3.5: + [<https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&product=GlusterFS&f1=keywords&f2=version&o1=nowords&o2=regexp&v1=Triaged&v2>=\^3.5 + Bugzilla link] +- New bugs against version 3.4: + [<https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&product=GlusterFS&f1=keywords&f2=version&o1=nowords&o2=regexp&v1=Triaged&v2>=\^3.4 + Bugzilla link] + +- [<https://bugzilla.redhat.com/page.cgi?id=browse.html&product=GlusterFS&product_version>=&bug\_status=all&tab=recents + bugzilla tracker] (can include already Triaged bugs) + +- [Untriaged NetBSD + bugs](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&keywords=Triaged&keywords_type=nowords&op_sys=NetBSD&product=GlusterFS) +- [Untriaged FreeBSD + bugs](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&keywords=Triaged&keywords_type=nowords&op_sys=FreeBSD&product=GlusterFS) +- [Untriaged Mac OS + bugs](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&keywords=Triaged&keywords_type=nowords&op_sys=Mac%20OS&product=GlusterFS) + +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. + +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](http://www.gluster.org/community/index.html) before changing +something. + +Is there enough information? +---------------------------- + +To make a report useful, the same rules apply as for +[bug reporting guidelines](./Bug Reporting Guidelines.md). + +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.* + +Other tips: + +- 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](https://bugzilla.redhat.com/query.cgi?format=advanced). 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. + +You can also take a look at +https://bugzilla.redhat.com/page.cgi?id=browse.html&product=GlusterFS&product_version>=&bug\_status=all&tab=duplicates's +list of existing duplicates + +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](https://bugzilla.redhat.com/query.cgi?format=advanced). + Example: search from "2011-01-01" or "-730d" (to cover the last two + years) to "Now". + +Are the fields correct? +----------------------- + +### Summary + +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](http://review.gluster.org) (see +[Simplified dev workflow](./Simplified Development Workflow.md)) + +### Severity And Priority + +Please see below for information on the available values and their +meanings. + +#### Severity + +This field is a pull-down of the external weighting of the bug report's +importance and can have the following values: + + Severity |Definition + -------------|------------------------------------------------------------------------------------------------------------------------------------------------------------- + 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 + +#### Priority + +This field is a pull-down of the internal weighting of the bug report's +importance and can have the following values: + + Priority |Definition + -------------|------------------------ + urgent |extremely important + high |very important + medium |average importance + 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. + +### Keywords + +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](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&keywords=Triaged&product=GlusterFS). + +**EasyFix** +: By adding the **EasyFix** keyword, the bug gets added to the [list + of bugs that should be simple to fix](./Easy Fix Bugs.md). + 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](https://bugzilla.redhat.com/showdependencytree.cgi?maxdepth=2&hide_resolved=1&id=glusterfs-3.6.0) + +**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 bugs@gluster.org +on the bug. + +Resolving bug reports +--------------------- + +See the [Bug report life cycle](./Bug report Life Cycle.md) for +the meaning of the bug status and resolutions. + +Example of Triaged Bugs +----------------------- + +This Bugzilla +[filter](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&keywords=Triaged&keywords_type=anywords&list_id=2739593&product=GlusterFS&query_format=advanced) +will list NEW, Triaged Bugs |