Cocoa and Objective-C: Up and Running (by me) is now available from O'Reilly.

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/:

ADC Connect Home Page

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

Create ADC Account


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:

Apple Bug Reporter Welcome Page


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:

Apple Bug Reporter New Issue


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:

Apple Bug Reporter Issue List


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

Apple Bug Reporter Issue Filters


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.
Design Element
Using RadarWeb: The Apple Bug Reporter
Posted May 05, 2007 — 15 comments below




 

Charles — May 05, 07 4040

You ought to clarify that DTS is not a free service like Bug Reporter. The minimum requirement is a $499 ADC Select membership and you get 2 DTS incidents per year.

Scott Stevenson — May 05, 07 4041 Scotty the Leopard

@Charles: You ought to clarify that DTS is not a free service like Bug Reporter
True, though you actually don't need a Select membership to purchase DTS support. A Select membership comes with two incidents, but you can purchase them individually for $195, as well. That may sound like a lot, but figure an individual consultant could easily charge $150 per hour. The DTS route also has the distinct advantage of getting answers from people who actually work at Apple and have access to engineers and source code.

Clearly, though, the Select membership is a pretty good deal. It nearly pays for itself with just the two DTS incidents, but that doesn't even factor in the hardware discount, seed access, copy of the final shipping OS, and so on.

Charles — May 05, 07 4042

Ah, thanks for the clarification. I looked and saw that DTS has a per-incident pricing but I couldn't find the $195 price.
My own Select membership just ran out, but I never used my 2 DTS incidents. I never came up with any bugs I could blame on Apple rather than my own poor coding.

Kenneth — May 05, 07 4043

I remember having used DTS with my free ADC membership without paying. That was in 2005 if i'm correct. Weird.

Marco Masser — May 06, 07 4045

IIRC, you can transfer almost all the goodies that a select membership gives you to any other ADC account. Which means, if your DTS is about to expire and you know someone who could need it, you can transfer it to their account.
Maybe that is what happend to you, Kenneth?

Patrick — May 06, 07 4046

Although recently restyled, I still find Bug Reporter to be one of the worst bug systems in use today. The name probably says it all: it is a bug reporter, not a bug tracker. It is a black box for dropping of your bug reports. Anyone who has experience with more capable alternatives will get frustrated with it very soon.

The biggest problem with it is that you're confined to your own bugs. Sure, there now is a search function, but it still only searches your own bugs... It would be incredibly useful to be able search all bugs in the database, before filing a report. To be able to amend existing reports instead of creating duplicates. To get instant confirmation that your bug is indeed a bug. To get a workaround suggestion for it.

In my experience, any non-trivial coding project for Mac OS X runs into a few bugs. Bug Reporter could be a useful tool while navigating these situations. At the moment it is not.

Blain — May 06, 07 4047

As frustrating as it is, it's done intentionally like that. If the bug's already listed, you're less likely to add in your take on it, which might have additional, crucial information that wasn't in the previous bug listings. It ironically also forces Apple to maintain the bug tracking better, because nobody else can do it, and they can't assume devs are sorting the bugs into the right categories themselves.

The other reason that it only displays what you already know is to avoid revealing things. That is, searching the database for known exploits or possible entries for such. Or for using the database to guess private information regarding unannounced software. Apparently, someone had listed 'MacOS X does not work on intel CPUs' as a bug before the 2005 WWDC. Imagine if they saw that issue closed as 'resolved' before then!

Still, however, it would be nice if a duplicate bug wasn't 'closed' in as much 'confirmed' or some other word that connotes "Still open, found elsewhere, but we're working on it." And that duplicate bugs could see workarounds. IE, find the bug, post it, and after submitting the bug and it's determined to be a duplicate, instant response of known workarounds, so you can't simply troll to find bugs.

Maybe I should send these requests in to radar...

Scott Stevenson — May 06, 07 4049 Scotty the Leopard

@Marco Masser: Which means, if your DTS is about to expire and you know someone who could need it, you can transfer it to their account

I believe the terms of use restrict transfer to those within your organization. That certainly seems to be the intention anyway.

@Patrick: The biggest problem with it is that you're confined to your own bugs. Sure, there now is a search function, but it still only searches your own bugs...

As Blain says, that's a conscious decision. Many of the bugs contain confidential information, and not just information about Apple products. Third party developers want to be able to discuss how their applications are using API without the general public watching what they're doing. There is, however, a tracking aspect to the tool, in that it allows you track and see the status of your own bugs.

Patrick — May 06, 07 4050

I don't think the arguments for keeping the bug database as closed as it is are ultimately convincing. It would be relatively easy in this web 2.0 age to provide a bug tracking solution that is openly accessible but still provides confidentiality when necessary.

I would like to see Bug Reporter evolve into a 'two way' system. Instead of just putting information in, I would like to get information out as well. A side effect would be that more people would use Bug Reporter, which would be a good thing for all parties involved (hence this Theocacao article?).

Another Bug Reporter peeve: I'd like a 'confirmed' status for submitted bugs. Simple things like that somehow give me a considerable sense of gratification. Maybe I'm not that hard to please after all ;-)

I'll add it to the 'open' stack.

Scott Stevenson — May 06, 07 4052 Scotty the Leopard

It would be relatively easy in this web 2.0 age to provide a bug tracking solution that is openly accessible but still provides confidentiality when necessary.

I don't understand. Why does Web 2.0 make it easy?

Anonymous Coward — May 07, 07 4063

This is cool.

This way I can work for a multi-billion dollar corporation for free!

blain — May 07, 07 4066

It would be relatively easy in this web 2.0 age to provide a bug tracking solution that is openly accessible but still provides confidentiality when necessary.

It's not a technology issue, it's a cultural issue. We're also talking about the same Apple where fans scoured the job listings for hints of where the next Apple Store would open, or the US Patent and Trademark Office entries to see what names Apple has registered, or even random urls at apple.com to see if there's any information uploaded but unlinked. I fear the amount of effort needed to filter and confidential-ize any unannounced features would outweigh things.

That said, however, it would be nice to have a secondary, more accessible bug tracking database, for things already open source like Darwin code, or linking to Apache's bug tracker if it's an issue with OSS projects that Apple uses. But this would not be easy to do.

Another Bug Reporter peeve: I'd like a 'confirmed' status for submitted bugs. Simple things like that somehow give me a considerable sense of gratification.

This I can agree with. Confirmed could also be used for 'closed due to duplicate'. Let us know we're not crazy.

This is cool. I'm trolling! Whee!

How do I translate 'Letting Apple know about bugs saves us time and money when we don't have to make the workarounds, and therefore, is a win-win situation' into Slashdot-ese?

In Soviet Russia, Natalie Portman Natalie Portman Grits Old people in Korea Beowulf Cluster Cowboy Neal?

Oldster — May 09, 07 4084

Long ago, before Darwin was sent to OpenDarwin.org (much longer than after Apple took it back), Apple DID have a world-viewable bug tracker.

I searched through it, trolling for indications my pet peeves were being fixed, and it was interesting. The bug that there was no /dev/random was originally scoffed at by Apple engineers until wsanchez explained it was a serious issue, and that crypto tools depended on it. Then, there was a discussion of how to implement it. Apple decided against using the FreeBSD /dav/random in favor of a home-grown Yarrow-based implementation that is non-blocking (but is willing to hand out more entropy than it really has, whoops).

I'm not sure what Apple is doing with /dev/random going forward, but the last time I checked the source /dev/random used entropy periodically scavenged from SecurityServer ... on a schedule that was independent of /dev/random's actual entropy consumption by users. Also, there's no actual difference between random and urandom on Darwin the last time I looked.

You could follow each developer's post, see where each one wanted to go ... it was very interesting.

You could also find annoying unsolved crashers languishing. Could be an embarrassment. I fully understand Apple shutting down public access to the live bug tracker, especially in light of secrecy related to upcoming hardware, etc. Live code access is just too hard to screen for "secrets".

Ahh, the good ol' days.

Anonymous Coward — May 11, 07 4095

Yeah but the win-win is both Apple.

You report your bug, but if you're doing anything else than hobby coding, you'll still have to work around it, because Apple may a) not fix it, b) fix it in the next release c) fix it in sometime in the unknown future.

Problems: Apple won't tell you if they will fix it. Apple won't tell you when a fix will be released.

It doesn't help other developers, because the only way for them to find out about this bug (possibly) is entering and waiting for it becoming a duplicate. There is no list of bugs from Apple. So developer time on the outside of Apple is squandered mercilessly, reproducing and entering always the same bugs. Good for Apple though, because they get more test cases.

Apple on the other hand get's quality control for free. For Apple's beta phases it's even better, because top-notch developers will happily pay for the privilege of getting preview-releases (premier, select developer status) and report bugs for free.

Win-Win indeed.

If this wasn't Apple but IBM people would see a little clearer on this subject.

Scott Stevenson — May 12, 07 4103 Scotty the Leopard

Apple won't tell you if they will fix it. Apple won't tell you when a fix will be released.

If something will not be fixed, it will be marked as something along the lines of "behaves correctly." Assigning a particular ship date to each request is completely impractical. Again, bug reporter is not just for "bugs," it's for any sort of enhancement. Knowing the ship date of a particular feature or fix for Mac OS X has much different ramifications than the ship date for a particular issue in, say, SQLite or Apache.

So developer time on the outside of Apple is squandered mercilessly, reproducing and entering always the same bugs. Good for Apple though, because they get more test cases.

The additional test cases are often essential to fixing the issue. As a developer, you must realize that when you can narrow the point of failure, the fix is much easier to implement. If you have one reported incident, it could be due to anything, including somebody spilling coffee on the keyboard.

Apple on the other hand get's quality control for free. For Apple's beta phases it's even better, because top-notch developers will happily pay for the privilege of getting preview-releases

Well, it's certainly not for free, because people have to be employeed to screen all of that feedback. In any case, just by participating in the world you're constantly helping other people make money. Even contributing to fully open source projects helps for-profit companies that use that code in various ways. Many people here are employed by for-profit companies.

You don't have to use the tool or sign up for the developer program, of course. I don't think that occassionally spending 15 minutes to write up an issue is that big of a deal. The point of this post was to let people know that this is an option available to them they can exercise if they choose.




 

Comments Temporarily Disabled

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




Technorati Profile
Copyright © Scott Stevenson 2004-2008