How to write a UI-Review

If this is your first time doing a UI-Review or you're experienced and would just like a more detailed check list to follow then you've come to the right page. This article discusses how to start a UI-Review using the GNOME bugzilla system, what to look for when doing a UI-Review and some rules of engagement.


  1. Choose a module to review
  2. Search old reviews for your module
  3. Organize an old review into a new review
  4. Create a UI-Review Umbrella Bug
  5. Create a new UI-Review Component Bug
  6. Reviewing the Module


Choose a module to review

Look to the latest ui-review's to see what hasn't been done or look for ui-reviews that are in need of some help. Some reviews are continuations from the previous ui-review run and were never completed, these probably need extra help.

Note: I use module and product interchangeably in this guide, because they essentially the same thing, but I personally don't like to use the word "product". :-)

Search old reviews for your module

If you're picking a module that doesn't have a review listed on the start page do a search under the module you've picked for keyword ui-review first, if you get no results do a search with just the keyword usability.

Organize an old review into a new review

If you found a ui-review under your module start investigating what happened with it. You may want to continue the review that was done or start a new. If you're going to continue, put a comment in the bug that says you're continuing this review, also add your email to the CC list and submit those changes. If you are going to open a new bug be sure to take all the old relevant information from the old bug, like dependencies on other bugs or comments that are still relevant.

If there was no previous ui-review found, you should have found at least a couple bugs under the usability keyword. Keep the usability bugs in mind when you're starting your review.

Create a UI-Review Umbrella Bug

If there wasn't a ui-review bug already or you're taking an old bug and creating a new one from it, here's how we want to structure the bugs. Please use this naming scheme as it makes it easier for us to look at from a dependency tree. 

[UI-REVIEW] *module_name* umbrella bug
An example of this using the gnome-panel module would look like: 
[UI-REVIEW] gnome-panel umbrella bug
In the example you see the 'gnome-panel umbrella bug' is the first bug you'll create in your ui-review. This bug is the indicator of when your review has been completed, explained more below.

Make certain to put the email address you used for bugzilla in the Assigned To field.

Make certain you're creating this new bug under the correct product for what you want to review. The component option should be 'general' for the 'umbrella bug' and specific to the review for the component bug.

Create a new UI-Review Component Bug

For each component of the ui-review that you examine in your module you'll open a bug that this 'umbrella bug' depends on. Then when all the individual component review bugs have been settled your 'umbrella bug' can be closed indicating that your ui-review is done. The result of this is a system of bug dependencies based which provides us a way to analyze the progress of a review and make sure some pieces of the review are not blocked because they are lumped together with other pieces.

Through a scheme like this the dependency tree of our ui-review ends up looking like so:

An example of this using the gnome-panel module would look like: Don't forget! As you create each new component bug, be sure to place the new bug number in the dependency of your 'umbrella bug'. The dependency field will end up looking like a comma separated list of bug numbers (78900,5648,8493,93874). Once you put your first dependency in you'll be able to view the dependency tree which tells you what component bugs are linked to the 'umbrella bug'.

TIP! When creating your bug, don't forget these values

Reviewing the Module

I'm still working on this section, for now just use the checklist on the GUP site.