[ubuntu-x] Doc updates - bug research

[Bryce Harrington]

Hi all,

With Gutsy in the can, I've taken some time to try documenting some of
the debugging procedures.  I've noticed there are several distinct
phases in the bug work:  a. reporting, b. triaging, c. research,
d. analysis, e. testing, and f. packaging.  The following doc focuses on
step c.  I'd love feedback/wordsmithing/etc. on this.

Bryce


V.  Bug Research
========================================================================
For some trivial bugs, a fix is obvious once the basic information is
gathered, but for the vast majority some additional investigation is
needed.

Much of this sleuthing merely requires skill with google and basic
understanding of Xorg jargon, and since the vast majority of Ubuntu's X
bugs are solved through this basic gumshoe work, this is an extremely
valuable way for non-programmers with a technical bent to make huge
improvements to Ubuntu.

You'll probably come up with your own process for researching bugs, and
in truth different kinds of bugs will benefit from different research
approaches, however in general you'd do something like this:

  1.  Review the log files for any error messages.  While many bugs
      won't have error messages, for those that do, you can probably
      skip steps 2 and 3.

      It may be worthwhile at this point to request additional files or
      command output from the reporters, such as gdb backtraces, strace
      output, etc.  Use the debugging X resources at wiki.ubuntu.com,
      debian.org, and freedesktop.org for ideas.

  2.  Review reports from others who experience the same issue.  Often
      hearing additional perspectives on a problem can give much better
      insight into the issue.

      If there are dupes associated with the bug report, read each of
      those.

      Search for other bug reports with similar problem descriptions, or
      that contain similar keywords, error messages, etc.

      If multiple people have commented on a bug or its dupes, compare
      their configs to see if there are obvious commonalities (e.g., is
      everyone using the same driver?  Same chipset family?)  If there
      seems to be a commonality, search debian and freedesktop.org for
      other bug reports regarding that hardware.

  3.  If you have hardware and software similar to the reporter's, see
      if you can reproduce it yourself.  Being able to reproduce a bug
      locally often can save you a lot of time trying to figure things
      out, and allows you to directly test workarounds and fixes.

  4.  Search for other existing reports of the issue.  If you've had
      luck with steps 1-3, that may give you good search terms,
      otherwise you'll need to rely on intuition.  Places to search
      include google, bugs.debian.org, bugs.freedesktop.org,
      ubuntuforums.org, and launchpad.  Sometimes it helps to include
      "ubuntu" in the search phrase.

      Be aware that many suggested solutions available on the net are
      incorrect, incomplete, or inappropriate for Ubuntu, so use your
      judgement, and ask the reporter to try out ones that seem most
      likely.

      If you find a match, attach it to the bug report via the
      "Also affects project..." link.

      This step 4 is the most important Researcher duty.

  5.  Look and see if there is a newer version of the package available
      upstream than what the reporter has installed.  If so, review the
      changelog (if available) to see if there are changes that sound
      relevant to this issue.

      If so, then see if someone has packaged the new version yet.  If
      not, find a Ubuntu X packager and ask if they can produce a test
      package of the new release; make sure to let them know you suspect
      it may address this bug.

  6.  If in your searching you run across patches that look relevant,
      upload them to the bug report for people to test.  Be sure to
      check the "patch" checkbox, as this allows packagers to query for
      these later.

      It may also be worthwhile to make mention of the patch to an X
      developer or packager at #ubuntu-x on freenode, or via the
      ubuntu-x mailing list.  They can produce a .deb including this
      patch for testing, to confirm or rule out the fix.

  7.  Sometimes it is useful to have those that can replicate the issue
      try older versions of packages or of Ubuntu.  For example, it may
      be worthwhile to have them test for the bug on prior Ubuntu Live
      CDs (but be aware that older versions may use different drivers,
      so be sure to have them collect necessary log and config files so
      you can compare configuration differences.)

      You can also have them try downgrading specific packages, such as
      if you suspect the error is a regression in a new version of a
      driver or the xserver.  For example, to downgrade the xserver:

         apt-get install xserver-xorg-core=2:1.3.0.0.dfsg-4ubuntu

      If an older version fixes the issue, then possibly you can bisect
      things down to find a specific patch causing the issue.  See the
      Analysis section for how to do this.

  8.  If you've been lucky and a patch has been found that fixes the
      issue, you're done!

      Otherwise, deeper analysis will be required.  For now, finish up
      the research phase by doing the following:

      * Summarize your findings.  Restate the problem in your own words,
        especially if you were able to make some progress narrowing in
        on the cause, or have a suspicion about where the bug may lay.
        Include any ideas you weren't able to prove, or questions you
        were unable to answer.

      * If appropriate, report the bug upstream either to Debian or Xorg
        (or maybe both).  Be sure to include all relevant files, logs,
        backtraces, photos, etc. and a link to the Ubuntu bug report in
        Launchpad.  Summarize the research you did, patches that were
        tested, and any other details that may be relevant.

Note in doing bug research that it's important to distinguish between
"workarounds" and "fixes".  Workarounds enable the user to get their own
system back to functional order.  Fixes solve the issue for everyone,
and prevent it from being an issue in the future.  Workarounds are worth
mentioning on the bug, so other users experiencing the issue can solve
it locally, but the bug can only be considered finished once a fix has
been released.