USERID_10868 stevenf.com: How to report a bug in a Mac OS X application stevenf.com The personal blog of Steven Frank Elsewhere: Email - RSS - Twitter - Flickr - Xbox - Panic ← Earlier Later → September 8, 2008 11:27 AM Bugs happen. It's a fact of life. Although you may not be in the mood at the exact moment they strike, the best possible thing you can do is file a bug report with the developer. You may not get an immediate solution, but you will provide extremely valuable forensic information that should help the developer fix the problem over the long term. Here's how to report a bug effectively. Stay calm You probably don't like it when people yell at you and developers are human too. A good developer will do their best to assist you regardless of your mood, but it's best for everyone involved to stay focused on the problem at hand and not let emotions take over, if at all possible. Quite often the person you're corresponding with is not to blame for the problem you're experiencing, so don't subject them to misplaced anger when they are trying to help you, or you'll put them on the defensive and make them dread your calls and emails. Don't make assumptions Here are some assumptions that developers commonly see from users: "This should be easy to fix." Maybe. Maybe not. Applications may have many subtle interactions in their underlying code. Anyone who has been a developer for a long enough period of time can tell you a story of making a one line change to their code that lead to disastrous results application-wide. Good developers will make even very small changes carefully, and test every step of the way to make sure this doesn't happen -- but that process doesn't always fall into the "easy" category. In a way it's a compliment to the developer that their application is so simple to use that you didn't suspect its underlying complexity. "They must have seen this before." Don't count on it. Even bugs that seem trivial and obvious to you may honestly have never been seen by the developer because the way you use the program is different from the way they use the program. You should always report bugs, even small ones. Developers may even prioritize bug fixes by the number of reports they receive about a particular bug, so don't be afraid that you're reporting the same bug as someone else -- this is actually a good thing. It provides data to the developer about how widespread the issue is. Try it from a new user account Sometimes a completely unrelated application can introduce problems with the application you're actually trying to use. A classic example of this is people over-aggressively configuring firewalls and then becoming angry when their network applications can't connect anywhere. Mac OS X makes it easy to try an application in an almost completely clean environment -- just create a new user account from System Preferences, log in as that user, and try to reproduce the bug there. You might just be surprised to find that the "bug" has magically disappeared. It may sound silly, but time and time again this has pointed people to application conflicts that they would have never even considered. If the bug isn't reproducible in the new user account, return to your regular account and systematically remove or disable applications, input managers, System Preferences panes, extensions, or other software that may be getting in the way, re-testing as you go. Include reproducible steps if you can The single most useful thing you can do when filing a bug report is to include a numbered list of steps that trigger the bug for you every time, like this: Start the application Click on the File menu Choose Print ... etc ... Not all bugs are consistently reproducible -- but if your bug is reproducible, and can be reduced to a series of steps like this, it's as good as fixed once an engineer gets hold of it. Engineers love bug reports like this because it eliminates so much guesswork and trial-and-error. Be meticulous and specific, but try to reduce the problem to the smallest number of steps you can. Say the problem occurs if you open an image, crop it, then save the image. Try eliminating the cropping step and see if the problem remains -- it may not be necessary to trigger the bug. Include expected and actual results Sometimes users file bugs against the designed behavior of the program: "When I do X and Y, Z happens!" -- But, as far as the developer is concerned, Z is what is supposed to happen when you do X and Y. To avoid this, it's best to include "expected" and "actual" results after your list of steps. For example: Start the application Click on the File menu Choose Print Expected Result: The Print dialog should appear. Actual Result: The program just beeps. This helps the developer determine if you've found an actual bug, if you have a misunderstanding about how the program works, or if the developer needs to re-work or rename a feature because a large number of people have a misunderstanding about what it's supposed to do. Include the entire text of error messages Be sure to tell the developer whether or not an error message is generated as a result of the problem. If an error message does appear, it's very important that you include its exact wording. There may be multiple error messages in the application with similar wording. BAD: "I always get an error message when I print" BAD: "I always get an error message when I print, something about a driver" BETTER: "I always get an error message when I print: 'Driver could not be found'" Briefly summarize your system configuration A full System Profiler report is not necessary in most cases for third-party application bugs. But a couple of sentences describing which model of Mac you have, and which specific version of the operating system (is it 10.5.2 or 10.5.3?) you're using may provide valuable information. Include screenshots if you can A picture is worth 1,000 words, and nowhere is this more true than in your bug report. You might not think there's any difference between typing "I get a 'file not found' error" and sending a screenshot of said error, but the developer may notice something going on elsewhere in the application's window that provides the vital clue to the true underlying cause. Don't forget about Mac OS X's built-in screenshot tool. Cmd-shift-3 will capture your entire screen to a file. Cmd-shift-4 will capture a rectangular area of your choice to a file. You can further use a tool like Skitch to add arrows, circle areas of interest, or redact confidential information that may be included in the screenshot. Drop these images right into your email. If you experience a kernel panic or serious hardware failure that prevents you from using the built-in screenshot feature, reach for the nearest digital camera and literally take a picture of the screen. Include a video if you can If a picture is worth 1,000 words, a video is worth at least 10,000. Recording a video of yourself triggering the bug provides incredibly useful information to the developer about how you're using the application, and notable things about your work process that may be crucial to identifying the cause of the bug. Screenflick is an inexpensive tool that lets you record a movie from a specific rectangular area of your screen. SnapzPro is another popular option. Jing is a free web-based video capture tool. Include Console messages In your Applications > Utilities folder, you'll find an application called Console. If you open it and choose "All Messages" from the top of the source list, you'll see hundreds of messages that are probably meaningless to you -- but may be very meaningful to the developer. To use the Console effectively, open it up and let it sit in the background while you reproduce your bug. If the application logs a Console message at the precise moment you trigger the bug, it is probably very relevant, and should be included in your bug report. You can simply select the relevant messages, then copy/paste them into your email. Sampling a hung application You've no doubt seen the infamous "spinning beachball" cursor. Many users misinterpret this as a crash, but in fact it just means that the application has not responded to user input for several seconds. The application may recover if given enough time, or it may be deadlocked and never respond. If this happens, always include a sample of the application in your bug report. To sample the application, open Applications > Utilities > Activity Monitor. Select the application that is not responding from the list, and click Sample Process in the toolbar. Activity Monitor will generate a sample in text format that you can copy and paste into your bug report. ("Sample Process" might not be in the toolbar by default on 10.4 Tiger. Use View > Customize Toolbar to add it if it's missing.) The sample tells the developer exactly what the program was so busy doing that it couldn't respond to user input. You should also include a sample in any bug report about excessive CPU usage. Crash logs The hallmark of a true crash is the "Application has unexpectedly quit" dialog. This dialog gives you the option of filing a crash report. The tragedy is that these reports go directly to Apple, and there they remain for all eternity. Developers never see these crash reports. If your problem application doesn't have a built-in crash reporter that sends the report to the developer, you'll get Apple's "unexpectedly quit" dialog. To help the developer, click "Report..." but instead of sending the report to Apple, copy and paste the report into an email to the developer. Conclusion It all comes down to this simple point: An unreported bug goes unfixed. Although it may not always seem like it, developers genuinely want you to have a good experience with their product. Even if they can't fix the problem straight away, they may be able to suggest a workaround to keep you afloat while they work on it. If you report bugs as you find them, following these guidelines, you'll have the best possible chance of getting your problem resolved. Copyright © 2002-2008 Steven Frank. All rights reserved. Any opinions stated are my own, and do not represent any other person or company.