Using RadarWeb: The Apple Bug Reporter

The Apple Bug Reporter is your single greatest tool in influencing the development of the platform. You don't need to be an actual programmer to use it, and it's much more than just a "bug reporter." It's a way to provide any kind of structured feedback on Apple software, hardware, documentation, services, or practically anything.

Before you can use the Bug Reporter, you need an ADC account. The basic "online" membership is free. First, go to http://connect.apple.com/:


Click the Join Now button, and fill out the information:



Log In to Apple Bug Reporter

Once your account is created, visit http://bugreport.apple.com/ and enter your user name and password. If you've spent any time at all reading Mac developer blogs, you've probably seen many references to "Radar" along with ticket numbers. Radar is Apple's issue tracking tool. The web-based front end to the system is officially called the Apple Bug Reporter, but it's unofficially known as RadarWeb, which you can see in the url.

When you log in, you'll see this welcome screen:



To create a new item, click New Problem in the title bar. Now remember, even though this says "problem," you can file an issue on anything, including usability suggestions, requests for additional clarity on documents, or new features. Here's what the page for a new issue looks like:



When you create a new issue, the goal is to be as clear about your intentions as possible. A high-quality report is likely to be taken much more seriously because you've taken the time to think the thing through, provided all of the relevant information, and felt strongly enough about the issue to explain it fully.

If the issue you're filing is a true bug — that is, something clearly doesn't work as intended — you should to provide as much information as possible about your system configuration and the exact steps needed to recreate the issue. Of course, not all issues can be recreated, but those that can be are the easiest to fix.

If the issue is a crash, you should provide the stack trace — the thing the CrashReporter tool provides — and the output from the System Profiler tool, which can be found in /Applications/Utilities. If the crash was caused by, say, opening a particular file, attach that file to the report, if possible.

Click on the "description format" link above the description box to get see a template. Here's an example:

Summary:
Kryptonite causes sluggishness in Superman.

Steps to Reproduce:
1. Locate chunk of Kryptonite
2. Locate Superman
3. Hand chunk of Kryptonite to Superman

Expected Results:
Superman is unaffected by a chunk of rock from his home planet.

Actual Results:
Superman can barely lift a piece of paper.

Regression:
Unknown.

Notes:
Different colors of Kryptonite have different effects.
Workaround: Separate Superman from the Kryptonite and
expose him to yellow sun.

If you're not sure how to classify your issue, click on the "Classification" link next to the classification dropdown for a brief explanation of each option.

Follow-Up and Tracking

Once you submit the form, your issue is given a unique id. That identifier is used for all further communication with ADC on that issue. You may receive emails from ADC requesting additional information. If so, you log back into the tool and simply add more text to the description field or, if appropriate, attach an additional file.

In some cases, you may receive an email which requests that you verify your issue was resolved in an update to the product. In other words, ADC may ask you to test if the issue was resolved in Mac OS X 10.x.x. If you can verify the issue was fixed, ADC can close the issue. To see a list of the issues you've filed, click "My Originated Problems" at the top of any page in the tool:



You can also use the secondary row of tabs — Attention, Open, Closed — to list issues that are in a particular state:



If you click the Search tab, you'll see a page that allows you to search your issues. Keep in mind that the search tool displays results from your filed issues, not the entire database. So don't bother trying to find secret stuff that way.

General Notes

There are many reasons an issue may be closed. One of the most common scenarios is an issue is closed as "Duplicate." At first glance, this may seem like rejection. It's not. It means others have run into the same thing and your report was valuable because it reaffirms the other instance was not an isolated case.

Even if you know an issue has already been filed by someone else, it's sometimes helpful to file your own description too, even if you know it will be marked as a duplicate. You may be able to provide additional details that help resolve the issue.

Keep in mind the Bug Reporter is not tech support. In other words, if you can't figure out how to do something with your computer or a piece of software, filing an issue won't help you. Also, if you have a code-level development question you need help with, you can enlist the help of Apple DTS, which exists specifically for this purpose. DTS is even more useful for help with pre-release software, since they have access to information no one else does.

Finally, it's worth reiterating that Bug Reporter is not just for code issues. If you think some part of the user interface for a Mac OS X system utility is a bit confusing, you can file an issue for that. If you'd like to request additional documentation on a topic, you can file an issue for that.

If you take one thing away from this article, understand that the Bug Reporter tool itself is not at all intimidating. If you have solid feedback to share, you should put it in written form so that the issue can be considered. It does no good to simply mention things on mailing lists — even cocoa-dev. You need to file an actual issue.

For additional details, check out the Bug Reporter FAQ and Bug Reporting Best Practices.

Comments Temporarily Disabled

I had to temporarily disable comments due to spam. I'll re-enable them soon.