Available languages:Italiano,

Introduction

This page provides guidelines for filing bugs related to Unity, how to provide the debugging information required to analyze the issue, and how to triage Unity bugs.

Filing bugs

Technical issues

Use the standard ubuntu bug reporting tool as it gathers detailed information regarding your systems configuration. From the command line:

ubuntu-bug unity

When a crasher occurs on your system you should automatically see a dialog inviting you to report the issue. It will collect useful information from your system, automatically as well. But here is what you can also add to your bug report to help us confirm the issue more easily:

• Provide the result of the command glxinfo. It contains important graphics information that can help us identify your issue. (glxinfo is provided by the package mesa-utils and is automatically run in Natty)
• Provide the complete description of your GPU and how much video RAM it has. For instance, the market name of your graphics card may be Radeon HD 4650 or NVidia Geforce GTX 280. For embedded Intel GPU, you don't need to provide that information.
• Your monitor resolution and screen setup (single, dual monitor, triple monitor)

If the dialog doesn't appear for some reason, see the "advanced" procedure below.

Even if the issue is actually in Compiz, it's still worth filing the bug against Unity, and we'll triage things to point to compiz as well. We're working very closely with the Compiz project. Now, if you know the bug is with Compiz, you can read the DebuggingCompiz page to help us get more info to solve the problem.

Design and usability issues

Because Unity is a user interface, all bugs that relate to user facing functionality need to be reported to the Unity design team. To report a user facing bug:

• Report the bug against the Ayatana Design project (NOT the 'Unity' project)

• Set the importance as you see fit

• If the bug is urgent ping JohnLea on #ayatana on freenode.

Filing Tips

• Priority is given to bugs in the stock install, so if you force-installed the cube or some other unmaintained plugin then try to reproduce on a stock install, remember we disable unmaintained plugins for a reason.
• Steps to reproduce is useful, is it happening with a certain theme or something else?

• Doing a unity --reset will reset your unity configuration, it might help to make a new user and try to see if you can reproduce it.

Advanced debugging procedure

Stale crashers

If apport did not automatically report the issue, you can check that a crasher trace has been collected by looking into the /var/crash directory. You should see a filename containing 'compiz'.

ls -altr /var/crash to list them in chronological order.

To manually file a bug report using a crash file:

• stay in your current X session

• add a window manager from a TTY if needed, ie CTRL-ALT-F1, login, DISPLAY=:0 metacity --replace

• then, from your X session, do: apport-bug -c /var/crash/<compiz crash file> and follow the procedure in the web page that should open shortly after you invoke this command. Note that focus issues may prevent the page to appear on the top, but look for a new browser window opened in your workspace.

Getting a stack trace

If for some reason apport was not enabled on your system, or if you have a reproducible issue we ask you to investigate, here is how you can generate a stack trace and inspect internal variables.

Ensure that you have the debugging symbols for the compiz, nux and unity packages.

Otherwise, from tty1 (Ctrl + Alt + F1)

$ unity --advanced-debug
GNU gdb (GDB) 7.2-ubuntu
Copyright (C) 2010 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "i686-linux-gnu".
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>

...

(gdb) set logging file unity.log
(gdb) set logging on
(gdb) b _exit
Function "_exit" not defined.
Make breakpoint pending on future shared library load? (y or [n])
[Answer yes (y)]

(gdb) run

[ and when compiz/unity crash, do...]

(gdb) bt full

[ then CTRL-D or re-run compiz to continue working ]

(gdb) run

You can also get a valgrind trace by running valgrind compiz --replace & in a terminal. This is a little bit slower to get because it runs compiz under emulation, but it does produce some output which isn't possible to get from gdb.

In extreme circumstances, we may ask you to use the crashhandler plugin from git and enable that in ccsm.

If you are experiencing a freeze, but can still use Ctrl-Alt-F1 to get to TTY1, you can use gdb to connect to the running compiz process, and get a backtrace. This will be invaluable information for us to debug your issue. To attach to the running process switch to TTY1, and follow these instructions.

$ sudo gdb compiz `pgrep compiz`

(gdb) set logging file unity.log
(gdb) set logging on
(gdb) bt full

[ then CTRL-D or re-run compiz to continue working ]

(gdb) run

You can then return to Unity by pressing Ctrl-Alt-F7.

Triaging instructions

Standard Operating Procedures

Failure to follow these simple guidelines may result in severe bodily harm at the hands of lamalex and didrocks.

Keeping Upstream and Downstream statuses in sync

The upstream and downstream DX workflow is a little bit different than other projects. Since there is almost no distro patching of DX projects packaging bugs are an extremely small subset of bugs reported. For this reason, the workflow is as follows.

1. Make sure the bug has both an upstream and downstream task.
2. Keep statuses in sync.
   • Upstream is the master. Sync downstream statuses to upstream.
   • The exception here is for downstream packages that are fix released. Occasionally a fix will be cherry-picked from unreleased DX code, and released in a package to fix a critical issue. In this case do not sync the downstream status to the upstream.

Marking affected components

During triaging it is often the case that a bug reported will actually be a bug in a base component. When this occurs it is imperative to add a task on that component. For example, if a bug in nux is crashing unity, a task should be added against nux, and statuses should be sync'd with nux as the master.

Similarly, if a bug is reported against a component project a task should be added against the super project. For example if a reporter reports a bug in nux, bamf, dee, etc. a task should be filed against unity so that we can keep track of all of the components in one place.

Marking as triaged

If a bug is present and have the steps to reproduce the problem the status can be set to "triaged". This status tells that the bug is ready for a developer to fix.

There are times when the original description of the bug is very little useful and the real problem gets described in the comments of the bug report, in these cases its wise for the triager to gather the steps from the comments and update the description of the bug report with clear steps to reproduce.

Design Bugs

Some bugs are not technical defects, but behavioral, or visual ones. These often require input from the design team before they can be fixed. When a bug is determined to be a design bug, it should have an Ayatana design task added to it, and its Unity status should be set to incomplete with the tag needs-design. After a design decision has been reached the Unity status should be set to triaged as there is then enough information for the bug to be fixed. See also the Blocked waiting for design decision canned response.

An example (real world) design bug: https://bugs.launchpad.net/unity/+bug/649560

Canned Responses

Canned "Call for Help" Template

Sometimes you know how a bug should be fixed (or a feature be implemented) but don't have time to do it, here's a template to add to your bug report to enable someone to contribute a fix:

This bug would be an ideal bug for someone to get started hacking on Unity, here's some information:

 * Time to fix: 3h (in hours)
 * Difficulty: bitesize/normal/difficult
 * Implementation:

     (pseudo code hand wavy idea goes here) 

 * Where to look: src/blah.cc
 * Workflow information: http://unity.ubuntu.com/getinvolved/ 

Bug Tags

These tags allow isolation of bugs into smaller groups, providing an easier and faster way to work on specific issues.

Testing a fix

Sometimes a developer might ask you to test a quick patch he came up with: check the Daily builds PPA to see if an updated version of Unity fixes the bugs you are experiencing. Be careful though, as those are daily builds that may break other things, and are to be considered unstable.

Known bugs

Known bugs, or missing features, are tracked in Launchpad and assigned to milestones to indicate when it is planned to be fixed and/or released.

• Unity milestones: https://bugs.launchpad.net/unity/+milestones

  • https://launchpad.net/unity/+milestone/3.4 - ubuntu milestones

    • https://launchpad.net/unity/+milestone/3.4.4 - weekly milestones

    • https://launchpad.net/unity/+milestone/3.4.4

  • https://launchpad.net/unity/+milestone/3.6

  • https://launchpad.net/unity/+milestone/3.8

Also see:

• DebuggingProcedures

CategoryBugSquad CategoryDebugging