Contents

  1. Introduction
  2. The Perfect Bug Report
  3. Automatic Bug Triage
  4. Package Classification
  5. Incomplete-With-Response Bug Triage
  6. Title Fixing
  7. Confirmed Bug Triage
  8. Description Tidying
  9. Marking Bugs Ready to be Upstreamed
  10. Reporting X issues upstream
  11. Upstreaming AMD fglrx issues
    1. fglrx Required Information for upstreaming
    2. fglrx Bug Upstreaming Procedure
    3. fglrx Upstream Statuses
  12. Upstream NVIDIA issues

Introduction

First, thanks for helping with X.org bug triage! X is a key piece of the Ubuntu architecture that *everyone* uses, and the bugs people experience tend to be pretty severe, so each and every bug you help move towards being solvable directly helps make Ubuntu better and easier for everyone.

The primary issue you'll deal with as a bug triager is that nearly all X bugs are reported without the information needed to classify and analyze the bug. This is where your work will make a big difference.

You don't need to be an expert with X to do this triage, as we've documented a lot of the common situations; so just regular Linux know-how will do.

You're welcome to dive right into the bugs at this point and triage away. You may already have a favorite X package to work on; if not, here is a list of all packages that the Ubuntu-X team maintains:

Triaging activities should include:

  1. Weed out non-X bugs (i.e. reassign kernel/gnome/plymouth/etc. bugs to appropriate packages).

  2. Move stuff out of the xorg package to the right X package.

  3. Set to Invalid if report doesn't define what the problem is, describes a non-issue or configuration problem, is just user confusion, or is otherwise unworkable or unhelpful to us.
  4. Verify reporter gave the right logs and steps to reproduce; else ask and set to Incomplete.
  5. Once all the needed info is there, set to Triaged and set its Priority.
  6. If the issue looks like something worthwhile for us to work on (e.g. affects a lot of users, or has an obvious fix), assign the bug to the canonical-x team for further handling.

The Perfect Bug Report

A perfect bug report begins with a perfect title. This should be constructed to indicate the chipset, features needed, short description of the problem, and condition(s) under which it appears. 

  [i321] (Needs Acme) X freezes on typing Any key when TLA turned on

A good bug description would include several sections: 

  [Problem]
  1-2 sentence description of problem

  [Discussion]
  Longer analysis or description of the problem (often just the original
  report with irrelevant bits deleted)

  [Workarounds]
  List of methods to work around the problem

  [System Environment]
  lspci, package versions, and other useful info on the hardware and
  software tested as affected by the problem.

  [Original Report]
  The original report text (if there's more discussion than what is
  above).

The bug report itself should include data files appropriate for the bug symptom. As a bare minimum it should include the Xorg.0.log. lspci -vvnn is also generally needed for video driver and xserver bugs. See X/Reporting for a more comprehensive listing of what is needed.

Ideally, the bug should also be tested against the newest version of the package that you can get your hands on, because if there is a newer released version, upstream generally will not respond to bug reports about an earlier release. For example, often newer versions will be posted to one of these semi-official Ubuntu-X PPAs:

Automatic Bug Triage

For Ubuntu-X, we have scripts to automatically do triage of several kinds of bugs for most X packages, so you do not need to spend time on these activities:

Package Classification

Most incoming X.org bugs get assigned to the xorg package since people don't know where to really file them. However, 99.9% of X bugs aren't actually bugs in this package, so we have to periodically go through and reassign them to the correct package. This is pretty easy, just time consuming.

Rules of thumb:

Incomplete-With-Response Bug Triage

Do a query against 'incomplete-with-response' bugs.

Title Fixing

Most people select poor titles for their bug reports. These can be improved pretty rapidly. The format to shoot for is: 

   Title:  [CHIP] (Needs...) Problem with/when/on ... [TECH]

CHIP comes from the VGA line of the lspci info. You need this only for bugs that are filed against video drivers. Look for something like this: 

01:00.0 VGA compatible controller [0300]: ATI Technologies Inc RV535 [Radeon X1650 Series] [1002:71c7] (rev 9e)

Here, CHIP is RV535. X1650 would also be acceptable. Best would be CHIP = "[RV535 X1650] ..."

For intel cards, CHIP will generally be something like "[i945]" or "[gm45]".

(Needs...) indicates that the bug needs a specific kind of fix, or some new feature we don't yet use by default. Usually you don't need this except in specific situations. For example, if the bug can be fixed with a Pipe-A quirk from X/Quirks, it should be "(Needs pipe-a quirk)", or if the issue is seen to go away when using some tech we don't ship as defaulted on, like UXA, you'd say "(Needs UXA)".

These statements are very helpful to include in the title because it helps the developers in making the decision about when to turn on a new tech, and flags bugs that can be closed when that new tech becomes available.

Problem with/when/on is the basic problem description. Often this needs rewording. Many people select titles that describe a generic symptom, like "corrupted graphics", or "black screen after install", which could occur for a number of different reasons. Improve them by looking for conditionals; often you can take them straight from the bug description. For example, "Corrupted graphics with dual head when using Xinerama on a Sony Vaio VGA-A270P".

Watch out for words like "randomly", "unpredictably", etc. - these usually indicate the reporter hasn't done enough to characterize the bug.

The reason revising the problem description is important, is because with generic titled bugs, other bug reporters will incorrectly assume they have the same bug and will "me-too" onto that bug rather than reporting their own issue; unfortunately this will result in them not getting their issue examined, and adds clutter to the original bug, making it harder and more time consuming to solve.

[TECH] indicates if the user found the issue with some non-default xorg.conf option or experimental technology. For example, if they are testing with Option "AccelMode" "UXA" in their xorg.conf, it would be [UXA]. If they are finding the bug when setting Option "DRI" "off", it would be [no DRI].

Don't include stuff like the driver name, e.g. "radeon driver fails..." (already implied by the package assignment), or the distro version name, e.g. "[jaunty]" (any bug open is assumed valid for the current development version; if not, "Nominate for release" should be used to target it properly.)

Confirmed Bug Triage

Once an X bug has made it to Confirmed status, it's generally got enough info and clarification to begin some basic troubleshooting.

If a bug is complete and ready to be forwarded upstream or solved in Ubuntu, or if there is a patch available, mark it Triaged (if you can).

Description Tidying

Many bug reports either a) are too terse, or b) ramble on too much. When we forward them upstream, the clearer the bug report's description is, the more likely it will be to get worked on.

A good bug description should have:

Marking Bugs Ready to be Upstreamed

Often bugs are best solved upstream, so many of our bugs should be filed upstream with them. However, it's important to ensure we send them only quality reports that have a high chance of being solved. It's our job to filter out reports that lack information or otherwise are inappropriate for upstream. This work can be divided into two steps: Marking bugs for upstreaming, and filing the upstream reports.

A bug is ready for upstreaming if it meets all the following criteria:

To mark a bug as ready for upstream, click "Also affects project", then leave the URL empty and click "Add to bug report", and "Confirm". This will leave a blank upstream task to search on later.

Reporting X issues upstream

To get issues addressed effectively, its important to provide complete information and clean, high-quality reports them. Indeed, much of the above bug work is geared with the objective of gathering sufficient information that upstream will be able to deal effectively with the problem.

Do a query on "Bugs that need reported upstream" (or bugs marked Triaged + not known upstream). X bugs are upstreamed to the bug tracker at http://bugzilla.freedesktop.org. Some guidelines to follow:

Here's a boilerplate for the bug report: 

I'm forwarding this bug from a Ubuntu reporter.
[Launchpad Bug URL]

[Problem]
...1-2 sentences...

[lspci]
...Bus ID (lspci -vvnn | head -n2)
...VGA IDs (lspci -vvnn | grep -A1 "VGA compatible")

[Original Report]
...

Here's a boilerplate to tell the original reporter: 

Hi, I've forwarded your bug upstream to [freedesktop url] - please subscribe to this bug in case upstream needs further information or wishes you to test something.  Thanks ahead of time!

Upstreaming AMD fglrx issues

fglrx Required Information for upstreaming

It is important that the issue be reproducible when upstreaming, because AMD needs to be able to reproduce the issue in-house in order to be able to accept it.

fglrx Bug Upstreaming Procedure

To mark a bug as needing to be upstreamed to AMD:

This marks the bug as one to be sent upstream.

fglrx Upstream Statuses

* - Note that due to NDA requirements, we may not be able to provide status information on some bugs until the fix is publicly available.

Upstream NVIDIA issues

See http://us.download.nvidia.com/XFree86/Linux-x86/1.0-9755/README/chapter-06.html

Also see: Bugs/HowToTriage CategoryXTeam

X/Triaging (last edited 2016-01-10 19:32:51 by penalvch)