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.

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)

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'.

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.

$ 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.

Make sure the bug has both an upstream and downstream task.

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.

Canned Responses

Situation

Response

Note

Patch needs author to sign Canonical Contributer agreement

Looks good but before we merge it we need you to sign the Canonical contributer agreement. It's a quick, but necessary step to getting your code into the tree. Luckily you only need to sign it once and it will apply to all other Canonical project contributions you may make in the future. http://www.canonical.com/contributors Make sure to CC David Barth when you send it in.

Blocked waiting for design decision

This bug is awaiting design feedback before progress can be made. Confirming that there is a question to be answered. Will be marked triaged when design gives a suitable direction forward.

This bug was reported against an old version of Unity. The new version of Unity is almost an entire rewrite based on very different technologies. Could you please check if this issue is present in the current version, and if it is reopen the bug to a NEW status.

Set the bug to WONTFIX, and let the user reopen it

Bug report on a development snapshot or with no recent activity

This bug was reported on a development snapshot of Unity but lacks elements for it to be actionable:
- there seems to be no reports of further occurences of the issue
- the bug cannot be reproduced reliably
- the information provided is not sufficient to track down the issue to a particular programming error.
Could you please check if this issue is present in the current version, and if it is reopen the bug to a NEW status.

Set the bug to INVALID, and let the user reopen it

Bugs that don't appear to be Unity related at all

The issue you're describing doesn't sound related to Unity. Could you log into a classic gnome session and see if this issue persists?

Things that design has done and has finished on that needs to be implemented.

...

...

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.