Jump to content

Bug management/How to triage

From mediawiki.org

This page is a guide how to triage bug reports in Wikimedia Phabricator. It is part of information on Triaging.

When we triage bugs, we review each bug's initial report, comments, reproducibility, and any attached patches. We discuss its priority and status and decide whether to change them, and sometimes recruit developers to fix the bug or implement the enhancement.

Before you start

Make sure that you have an account in Wikimedia Phabricator - follow the instructions how to create your account in Phabricator.

If you are not familiar with Phabricator yet, you may want to take a look at the Phabricator page on this wiki first.

Getting started: find reports to work on

There are many different techniques and approaches to find reports to triage. You can find some ideas at Bug management/Triage tasks.

If at any point you feel like you do not know what to do with a certain report, please first ask developers or contributors before changing something.

What and Why

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

Is there enough information?

To make a report useful, the same rules apply as for How to report a bug.

It's hard to generalize what makes a good report. For "average" reporters is definitely often helpful to have good steps to reproduce, a web address (URL) where to see the problem, or a MediaWiki software version in case it's their own wiki installation, and information about the browser and version used. 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).

Other tips:

  • If the report is not in English, an online translation service can sometimes help.
  • There should be only one issue/problem 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.
  • 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 Wikimedia 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, go to the "original" report, click "Merge Duplicates in" and enter the number of the duplicate report (like "T456789"). It can be helpful to shortly explain your action in a comment in the duplicate report for the reporter (or see "Help tools" at the bottom of this page).

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 T456789" (and replace 456789 by the bug number) so somebody else can take a look and help judging.

Tips for searching:

  • As it is often hard for reporters to find the right place (projects) where to file a report, also search for duplicates outside same project 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.
  • Try different variants of a word (e.g. search for "delete", "deleting" and "deletion" as long as T679 is not fixed), and also try similar words (e.g. search both for "delete" and "remove").
  • 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 "Updated After" on the search page. Example: search from "-2 years" (to cover the last two years).
  • See the Phabricator help on searching for more information.

Trying to reproduce

This is an optional step. Only try if you have time.

When you try to reproduce a bug, write down the exact steps to reproduce it, plus mention the operating system, browser and browser version that you used for it. This is very similar to the guidelines How to report a bug.

A template could be: 

I can reproduce the problem with the URL https://en.wikipedia.org/wiki/ExamplePage with InternetBrowser version 9.2 on Microsoft Windows XP3.
1. Go to the address above
2. Log in into the wiki
3. In the upper right corner, click the Link "Settings"
4. In the following page, click the checkbox in front of "Use Highlighting"
5. The checkbox should be enabled, but it stays empty. The checkbox is not greyed out either.

If you cannot reproduce the problem and the report is a bit older (more than 18 months; also see the MediaWiki Version lifecycle), you could add a similar comment like the one above (describing your setup and the steps that you tried) and kindly ask the reporters if this problem still happens, in case the reporter has time to check again.

If you get feedback from the reporter that the problem does not exist anymore you can change the status of the report as "declined" (or "resolved" if you can identify a specific code change that fixed the problem).

It is recommended to test on test2.wikipedia.org. You can find out which exact MediaWiki or extension software version a wiki runs by going to the page "Special:Version" (for example: http://test2.wikipedia.org/wiki/Special:Version.

Resolving bug reports

See the Bug report life cycle for the meaning of the bug statuses and resolutions.

Who and Where

Project tags

Ensure the report is added to the correct project project(s). A correct project ensures that people dealing with the relevant code or process eventually find it and deal with it; this requires the What and Why to be clear (at least superficially).

The rest of this section is optional.

Adding people to the "Subscribers" field or changing the "Assigned to" field

Normally, developers and potential assignees of an area are already subscribed by default, thanks to the project tag, but sometimes reports describe general issues or are filed against very broad Phabricator projects. Only if you know developers who work in the area covered by the bug report, and if you know that these developers accept getting subscribed or assigned to certain reports, you can add that person to the "Subscribers" field or even assign the bug report to them.

To get an idea of who works in which area, it can be helpful to:

By adding yourself to the Subscribers (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 which actions you will receive bugmail about.)

Cookie-licking: If you find an open report that has an assignee set for more than twelve months without any reported activity by that assignee, this might be "cookie-licking". You should add a comment explicitly addressing the assignee, like "This issue has been assigned to you a while ago. Could you please describe the progress / status and inform us whether you are still working (or realistically plan to work) on this issue? In case you do not plan to work on this task, should the assignee be removed and is the set priority realistic? Note that you can always claim a task again when you are actually planning to work on it. Thanks for your help!". If an assignee has not replied to such a request for an update for a while (several weeks), feel encouraged to remove the assignee from that task in combination with a comment explaining why you do so.

Tag projects and tracking tasks

In order to "tag" certain types or categories of bugs all across the different products, project tags are used. You can find a list of all tag projects here.

Sometimes so-called "tracking tasks" were used instead of projects (projects are often global while tracking tasks only refer to a certain subproject). Tracking tasks should be avoided.

When

Setting priority

You should only do this if you are an experienced triager and aware of development teams' plans. See Setting priorities. Skip this section if you are not yet.

Priority levels covers the meaning of the values, hence this section only provides additional information on the triage related process.

During triage, a Priority is assigned to a bug report. Project managers and maintainers use this field, in cooperation with the Bugwrangler, in order to plan development of fixes or features to address the bug report. The Priority field reflects reality but does not cause it.

In order for these fields to retain meaning and effectiveness, communication is essential. For example, the priority "Unbreak now!" has no meaning if no one has agreed to get it resolved quickly.

If you have made sure that a bug report deserves immediate priority, but do not know the developer who should work on it, then assign it to the manager and/or maintainer of the affected project). If you don't have any idea who to assign the bug to and you are still sure that the bug deserves this priority, then ask in IRC (#wikimedia-dev connect) for some help before giving it that priority.

Is it an outside problem?

If the problem happens because of a piece of software that is not developed by MediaWiki/Wikimedia developers the problem should be forwarded to the so-called "upstream" developers (MediaWiki/Wikimedia is called "downstream" in this context, as we are just users of that piece of software). You can find a list of software which is tracked elsewhere and used by Wikimedia, plus addresses of the corresponding bugtrackers here: Upstream projects#Components.

After forwarding a bug report to an upstream bugtracker, please edit the initial description of the bug report by adding the address of the upstream report (like: "Upstream report:" followed by the link). Please also add the "upstream" project to the report.

Advanced

Helper tools

Andre Klapper has shared a Greasemonkey script that he uses (Greasemonkey is a client side JavaScript extension that runs in Firefox and some other browsers). The script is available for download and everybody can install it to save some time!

The script includes stuff like

  • providing one-click stock comments,
  • colors MediaWiki extensions in the "Projects" field based on a manual list (e.g. "green = deployed")

Please contact Andre Klapper if you need help installing or understanding the code. Contributions are welcome!

Situation specific information

  • String or translation issues: You can get the technical ID of a string in the browser by attaching ?uselang=qqx to the web address. You can also append ?uselang=en to get a page in English.
  • Loading/network issues:
  • Performance/Profiling information: Adding &forceprofile=true to the end of the URL will include profiling information as an HTML comment in the page (it does not work on API). You have to make sure you are viewing an uncached hit if you want to gather profiling info, e.g. by looking at an old revision. You can also do things like using Firebug (Archived 2017-04-24 at the Wayback Machine) to manipulate the form and using an edit preview or the Special:Expandtemplates page. Doing ?action=purge&forceprofile=true only sometimes works. This is a Wikimedia specific hack (in StartProfiler.php) so it does not work on third party sites.
  • Purging: Adding &action=purge clears the page's server cache. This can be helpful for stuck pages and thumbnail issues. See WP:Purge for more information.
  • JavaScript errors: Browsers offer an error or debug console. If there is a problem or an error with JavaScript it should be printed in that console. Browser specific information: Chrome, Firefox ≥24, Internet Explorer, Opera, Safari). To get filenames in the output instead of a generic "load.php", reload the page in debug mode). If there's already a question mark in the URL, add &debug=true to the URL. If there's no question mark yet, add ?debug=true. Using debug=true bypasses Varnish.
  • Donation banners: To get them displayed, you can append ?force=1&banner=$name by replacing $name with the name of an active (green) campaign banner listed on the m:Special:CentralNotice page on the site. There are also "Preview on-wiki" links at m:Special:CentralNoticeBanners. You could also delete your centralnotice_fundraising web browser cookie if it exists (the cookie sets a hide flag which will stop CentralNotice from requesting a banner).
  • Pywikibot: Check that bug exists in both core and compat branches and if the bug can't be reproduced in one of the branches, note it in bug page.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Bug_management/How_to_triage&oldid=6335487"