Welcome to bug reporting best practices. I'm Paul Schreiber, a software engineer on the Mac OS X team. Today we're gonna talk about what happens when things go wrong. And when things go wrong in software we call that a bug. So, what do you do when you see a bug? Well, when you see a bug you write a bug report. You write a bug report because you want something to happen, you want some action to happen. And action means different things to different people.

And sometimes when your computer isn't working you wanna take different kinds of action against your computer. But instead what we wanna encourage you to do is to write a bug. And why is it that we file bugs? Well, we file bugs because we want to make better software. And if you file a bug against your own product it helps make your software better. And when you file bugs with us at Apple, it helps us improve Mac OS X.

So, what is it I mean when I say a bug? When it comes to software bug can mean one of two things. It can describe either a defect in a piece of software or an enhancement request, which is a suggestion for a new feature or an improvement to an existing feature.

And there are many different kinds of bugs you might run across and want to file. I'm gonna go over some of the most common ones. First type of bug is a security bug. A security bug means something very specific. It means there is, someone has access to files or system services they shouldn't or they've able that remotely execute code on your computer. Now, if you run into a bug in a security component, for example, something is wrong with a dialogue in the key chain access program, that's not a security bug. But it's still a bug. And it still should be filed.

Next type of bug is a crashing bug. And here we have the familiar, well hopefully not too familiar, panic screen on Mac OS X. When you see the kernel panic that means your entire computer has crashed. And that's definitely a bug. On Mac OS X when an application says it has unexpectedly quit that means the application has crashed. And if you see a dialogue like this, this means you should file a bug. When you see the familiar spinning rainbow curser here this means an application is unresponsive. And new on Leopard if an application is force quit while it's unresponsive you'll see this dialogue over here.

If an application is hanging or unresponsive file a bug. Another type of bug is a performance bug. A performance bug means that software is spinning or hanging or it's slow or it's leaking something like memory or mock ports, or file descriptors. If you see this happening file a bug.

The next type of bug is a cosmetic bug. And if you look over here to my left you'll see the familiar finder in photo dialogue. And this is from Tiger. And if you'll notice the iMac icon is jaggy and blurry. This is a bug. This bug's been fixed in Leopard.

Another type of but is an inconsistency. And that means when two pieces of software will do the same thing in two different ways. Over here we have two menus. We have the video menu from the DVD player and the video menu from QuickTime player. And yet, normal size is command two and here actual size is command one. So, if you see software accomplishing the same task in different ways that's a bug. The next type of bug I'm gonna show you is the usability bug. And the usability bug means something works but it could work better. Here is the open URL dialogue from QuickTime player.

Blank and as expected, the OK button is disabled. But if we start typing, we've got http://, the OK button highlights. If we were to click OK right now we'd get an error because this isn't a valid URL. So it makes more sense to disable the button until a valid URL is present and then you don't have to display an error to the user.

Next type of bug is a documentation bug. A documentation bug can mean several things. It can mean the documentation doesn't match the implementation. It could mean something isn't documented at all. It could mean the documentation is unclear or ambiguous. It could mean it's confusing. It could be something simple as a typo or spelling error. Here's an example of a functional bug in a piece of software. Behind me we have the familiar Connect to Server dialogue from the finder. I typed in ftp.apple.com and I click Connect. But the finder guessed wrong and it prepended afp:// to the host name.

Accessibility is a very important part of Mac OS X. And if you run into software that is not fully accessible, or behaves in unusual ways when using accessibility features like voice over, or a full keyboard access then you should file a bug. And finally, if you have any problems with sinking, if you have data that doesn't sink or if you have duplicate data or you have missing data, then that's definitely a bug.

So, who is it that should file a bug? Should you file a bug yourself? Should you ask is it okay first? You all should file bugs. If you see something wrong with software then file a bug. So, when I tell people they should always file a bug they have a few objections. And they might say well, Paul this seems like this is a really trivial bug. Maybe it's only a typo or the color is off, or.

It doesn't matter. File a bug. Next they'll say well Paul I only saw this problem once and I've never seen it again. Should I file a bug? Yes. You should file a bug. And finally people will say well this seems like it's a really obvious bug. I'm sure everybody has seen it.

You must have 12 copies of the bug. Should I file a bug? And the answer to that question is yes. File a bug. So, why should you file a bug even if you think we might already know about it? Well, it's much better to have five copies of a bug report than no copies whatsoever. And when you see a lot of reports of the same problem you know it's pretty wide spread and it'll help you prioritize that bug.

One thing I'd like to add is that a bug is a bug in the eye of the beholder. That means if it looks like a bug to you even if it was designed that way by the person who wrote the software it's still a bug. And you should file it because it confused you. Now, this doesn't mean to go and file the bug and then get it closed and file it again and keep arguing with them. But if something seems wrong to you as a user it's a bug.

Now, you don't always know when it is you're going to run into a bug. And it sometimes might happen when you're not ready or at an inconvenient time. So, if you wanna right a bug report there are a few steps you can do to make sure your map is set up for debugging.

And the first thing you're gonna wanna do is go into system preferences and go into sharing and turn on remote log in. This way you can insure you can go and log into your Mac through SSH and do any sort of analysis you might need to investigate the problem.

The next thing you're gonna wanna do is install some software. What software is it that you wanna install? First you wanna install the developer tools. And in addition to Xcode you've got Xray. You've got access to GDB. You've got several other useful performance and analysis tools. Aside from installing the developer tools you wanna install the chug tools, which gives you access to Shark, which is a terrific performance analysis tool. And we'll get into that a little bit later. And finally when you're setting up your Mac to debug you wanna take notes. And when I say you wanna take notes, you actually wanna take some notes down on paper.

Why do you wanna take them down on paper? Well, suppose that when you run into this bug it's taken over your Mac in such a way that you can't access the screens you need to look up this information? So what do you need to write down? First you wanna write down the IP address of your machine so you can log in remotely. Now, sometimes your IP address is dynamic or it changes a lot, or you might be somewhere where you have a self assigned address. In this case you want to know the Bonjour name of your Mac. And you can get that from sharing preferences.

If you're at school or at a workplace where you have a fixed host name, knowing that is also helpful. And finally you should write down the hardware Ethernet address of your Ethernet and AirPort interfaces. This is very useful if you're running into any sort of a networking problem.

So, if you run into a but and you're set up. Once you're right this bug report, where is it you should write the bug report? So if you've used some of our software you'll see there are a lot of different options for providing feedback to Apple. You have the crash dialogue.

If you're a WebKit or Safari developer you'll see you might be using Bugzilla. And you can see the report but to Apple button in the Safari tool bar. You might have the iChat feedback dialogue in Mac OS X 10.4.7 or later. If a connection attempt fails you might see the provide feedback menu item in applications like Keynote or iPhoto.

You might be using an email address to communicate with apple. In all these cases even if you provide feedback through one of these means you should use Apple Bug Reporter. An Apple Bug Reporter is available at bugreport.apple.com. So why do you need to use Apple Bug Reporter? Well two things happen, one is that you have are given a report number so you can go and follow up and add additional information to the bug. And you'll be given the opportunity to verify that the bug is fixed.

And secondly, if the engineers have a question for you or they require their information this way the have a means in which to contact you. So there are five parts to a good bug report. There are the bug's title, the bug's description, data about the problem, the configuration of the machine on which the problem occurred, and finally reproducibility. How easily does this bug occur? So let's start with the bug's title.

The title of the bug has to be clear and succinct. Remember that when you're writing your bug you don't have a lot of space for the title and you wanna convey as much information as you can. So, how do you do that? Well, you wanna think of the title as an advertisement for your bug. When you, people see your bug you want them to open it up and investigate it and fix your problem.

And a good way to do this is to start by making the first words of your bug title count. Good first words usually include the name of the program where you saw the problem. And because space is so limited it's important that you make every word in your title count.

What is it I mean when I say make every word count? Well you wanna admit things like explanatory, or chatter. People often say things such as it would be nice if my software did this. Or, I would really like it if your program did that. And this type of exposition, while appropriate in the bug's description, can be omitted from the bug's title. Second thing you can do is you can omit thorough words. So if you run into pronouns or articles or prepositions, usually you can remove them from the bug's title.

Sometimes when you are reading other people's bugs you'll come across prefixes And people, when screening and analyzing bugs will often prefix their title to make it easier for them to search and sort through bugs. And if you're responsible for a bug tracking system at your company this may be something that you'd wanna consider.

So I'm gonna show you three common prefixes. The first is the prefix ER. ER means enhancement request, which says that this bug describes and improvement and not a defect. The second title or second prefix is a build number. And here we have 8P2137, which is a build number for Mac OS X on Intel. Build numbers are especially helpful when you're writing bugs against pre released data or seed software. So, people know exactly what version of the software you saw the problem on.

And finally the prefix regression means that something used to work but has now stopped working. If you're a Safari or WebKit developer this is a very common prefix to run into. Now if your bug is about a particular error it's very helpful to include key words from the error message and the error number in the bug's title.

If you run into a bug that is about a crash or a hang then it's helpful to include the function name from the top of the stack trace at the end of your bug's title. You can get this from the crash report or you can get this from sample. Now, when you are doing this there are a couple of things that you want to omit.

If you see any low level functions related to memory management or string comparison or exception hailing at the top of the stack trays, skip over them and go down until you see the first part of the program that is performing the action which led to the problem and include that function at the end of the title.

And remember that your title needs to stand on its own. This bug title will be reviewed on a list of tens or hundreds of others of bugs. And it's gonna be out of context. The title is the most common way that engineers will search for you bug. So, when you're writing up the title think about if you were looking for that problem how would you search for it? There are couple of things you want to avoid in titles. The first is any clever puns. And I enjoy being witty as much as the next person. But when you're writing a bug title I have to remember two things. First is that your goal is to be objective and straight forward and communicate clearly.

And the second is that the person reading your bug might not be a native English speaker and might not get the joke. So, please avoid the use of puns in bug titles. Another thing to take not in is sometimes when people hear oh call attention to your bug, they think we're on eBay and we're gonna use all capitals or we're gonna put funny symbols in our bug titles. And please don't do this.

There are a couple of problems with it. First, thing it takes up more space when you use all capitals and it's harder to read. And when you use funny symbols it's harder for people to search for your bug. And finally, while I have not seen any actual examples of this in a bug, please don't use l33t speak in a bug title.

Let's take a look at an example of improving a bug title. So, suppose you ran into a problem where your program crashed and you could star by writing a bug title that says crash. But I can look at this here and say, hum, what does this mean? What crashed? What was going on when the crash occurred? So, you can improve this title a little bit by starting with the name of the program that crashed. And you can say finder crashed.

This is a little better but it's still missing some information because the finder is a very complex application and there can be a lot going on. So it helps if we describe what we were doing when we saw the crash. So, suppose we went to the go menu and we chose iDisk and finder crashed. So we could say finder crash connecting to iDisk. And this is a good bug title.

And if you were to write up a bug like this we'd be very happy. And most people could stop here. But there's something we can do to improve this title even further. Remember I mentioned we can add a prefix. And because this is a crashing bug we can look in the crash log, get the function name where the crash occurred. So, if we were to write 8P2137: finder crash connecting to iDisk in T container item, we would have a terrific bug title.

Here I have a couple of examples of titles, which can be improved. And for someone, suppose someone wrote up a bug that said smudge marks everywhere in Safari. And there are a couple of problems in this title. The first problem is that Safari is all the way at the end of the title. And it's the most important thing here because we know this bug is about Safari.

So it needs to go to the beginning. And the second part is what does it mean when we say smudge marks? What is a smudge mark? How do we get the smudge mark to show up in the first place? What's everywhere? So, suppose this is a problem we ran into when we were looking at QuickTime VR panoramas. So, we could write the bug title as Safari redraws QuickTime VR movies incorrectly during window resize. And this conveys a lot of information about what and how very quickly.

Another problem is sometimes when you run into a problem you're upset. And suppose you were doing an important demo or you had a presentation and your computer crashed or something went wrong and you would be angry. And you would say error this new iSmell application is a complete failure. iSmell is really iStink. This is terrible.

And I understand and I too would feel like it's a complete failure if it crashed on me during a demo. But instead of writing that think about how it failed. So, suppose you had this new fancy camera and it didn't work with your new fancy camera. So, you could write a bug that says iSmell is incompatible with the Sony CyberCube 3000MX.

And finally sometimes I run across a bug title that is so strange even I can't think of a way to improve it. So, please, please don't write bugs like that. So, let's sum up the best practices for writing a bug title. Start off with the build of the piece of software, which had the problem. Continue with the name of the application that had the problem.

Next, include a verb describing what you were doing to induce the problem. And, describe the situation that was gonna, that was happening when the problem occurred. And finally, in the case of crash or a hang, include the symbol name that you saw at the top of the stack trace. Alright let's move on to the second part of a bug report, or the bug's description.

The description had five parts, summary, steps to reproduce the problem, regression information, under what situation the problem does or doesn't occur, expected results and how the contrast with actual results, and finally any work around if one exists. Let's take a look at summary. When we talk about the description of the bug we really mean be descriptive.

And some of the best descriptive writing you might come across in the newspaper might be in the sports section. For example, a good sports writer would never write oh Hernandez threw a good curve ball. He'd write, it was the bottom of the ninth, they were two out, it was raining, they were down by a run, it was the three two count, the bases were loaded and then Hernandez threw a curve ball. So remember that the person reading your bug report wasn't there with you when the problem occurred. They don't know exactly what your set up is like. They don't know exactly all the things that you saw so you have to tell them.

So when you're summarizing you bug, the first thing that you should do is you should repeat the title. Why do you wanna repeat the title of the bug? Well, often as engineers investigate bugs they will change the title to reflect the underlined cause of the problem. When you repeat the title in the summary of the bug, you let everyone reading the bug report for the first time know what it is that you saw which lead you to write out the problem. Next you need to summarize the problem. Describe what was going on, describe what happened, describe why this was a problem. When you're summarizing your bug it's important that you're very specific.

For example, if you were to write a bug and you say Safari is slow, what does this mean? Does this mean Safari is slow compared to another browser? Does this mean Safari is slow compared to another version of Safari, or Safari on a different machine? And what is Safari slow doing.

Suppose Safari was slow allocating JavaScript arrays. So we could write that and say Safari is slow allocating JavaScript arrays. This is much clearer and it would be really helpful in this case to include some sample JavaScript or Shark profile of what Safari was doing at the time. Well, when you're writing your summary you have to describe the facts of the situation, that is what you saw and what you did and what you heard.

If the bug is about a particular error, the summary is a good place to include the exact text of the error message in any error number. Now, many error messages are very similar. So it's important to be precise here. If you can't get the exact text of the error message because say it appeared and it disappeared too quickly or it wasn't readable. That's okay write down what you can remember of the error and note that this is an approximation. So, someone doesn't waste a lot of time chasing down a false lead if the wording of another error message is very similar.

And it's important, when you're describing your problem to use specific references. What do I mean by specific references? Well instead of saying the window or the panel or the pallet, you would say the finder's inspector window. And instead of saying the round funny gray thing, you would say the spinning indeterminate progress indicator.

Now, how man here know what the spinning indeterminate progress indicator is? Alright like two guys. Well, this is the spinning indeterminate progress indicator. And if you didn't know that that's okay because what you can, there's two things that you can do when you run across something you don't know the name of.

The first, if it's a control like this you can go to the Apple human interface guidelines and look it up. But, if you don't have a copy of that handy or you don't have time, that's okay too. Instead, take a screen shot of the item in question and attach it to your bug, so that way people know what you mean.

Another thing you want to make sure of is to avoid the use of relative pronouns. So, instead of saying oh it crashed or that hung, or the problem was there. Describe specifically what application or window had the problem because by the third paragraph, the engineer reading the bug isn't necessarily sure what you're referring to when you say it or that.

Another thing to take note is the use of the words, the use of the word crash. If you say the system crashed be specific about what you actually mean. People will use this phrase to mean many things. They could say oh an application crashed. They could say the system did crash because we saw the kernel panic dial up. You could say the system hung and was unresponsive to use input or an application hung and maybe it came back later.

Or perhaps the system froze in such a way that it wasn't responding to user input from the keyboard or mouse but then maybe you could still SSH in and perform other actions. So, instead of saying the system crashed say what, which of these or other actions actually happened to you.

Another thing to note is that sometimes people will use slang terms or informal language to describe problems. And they'll say something looks bad or it's nonsense or this is odd. But odd to you isn't necessarily odd to the engineer reading the bug. So instead of doing this it's important to be precise.

And another way of being precise is to avoid the use of vague language. Sometimes people use the word nothing in the bug and they'll say nothing happens or this does nothing or this doesn't work. And instead of saying what didn't happen you should describe what did happen. For example, suppose you were trying to print and printing didn't work for you. So don't say printing, I tried to print and nothing happened. Say, for example, was the, think about what you saw.

When you clicked on the file menu was the print menu item enabled? When you chose print did the print dialogue appear? When the print dialogue appeared was your printer listed? When you clicked was the print button enabled? When you clicked print did the print dialogue go away? When the print dialogue went away did the progress dialogue come up? Did the progress dialogue ever go away? Did the printer proxy application launch and so on? So you could describe what you saw and at which point you stopped seeing what you expected to see.

Let's take a look at an example of improving a summary of a bug. And here's somebody that has written. Did you know the Finder eats CPU while connecting to a server at a Chinese restaurant? And you can look at this and say this is really confusing because I didn't know they served CPU at Chinese restaurants. And so, the first thing that you wanna do with this bug is you wanna get rid of some chatty language that's unnecessary. And we see did you know that, we can cross that out.

Next thing we see here is we can reverse the order of the clauses in this sentence to make it more clear what was happening. So if we say, so here we have, we removed the did you know that and we're now if we reverse the order of the clauses we get at a Chinese restaurant the finder eats CPU while connecting to a server.

So it's more clear we've described where we are and then we've described what happens. But we can improve this description even further by including specific information specific technical information about the problem. So, when we're at the restaurant it means we're actually using our EVDO modem. And eats CPU means using 90 percent CPU and the server we're connecting to is an FTP server.

I know I mentioned earlier if you're upset when you write a bug and you write the title in an angry way and you should avoid doing that. Likewise, when you're writing a bug description when summarizing the bug it's good to avoid the use of sarcasm even when you're upset. Think of how you would feel if you were to receive that type of bug report.

Another important thing to note is that you should be descriptive and not prescriptive when writing your bug summaries. And what do I mean by this? Well, you want to describe the problem that you saw and not necessarily what you think the solution should be. For example, suppose that you saw some text and you couldn't read it.

And so, you might write oh this text should be green. But the solution might not be to make the text green. It might be to make the text bigger or might be to change the size of the text. And you should let the engineer decide what the appropriate solution is. But you should let them know why this is a problem for you.

Next, it's important to differentiate speculation from the facts. And remember the facts are what you saw and what you did and what you heard. And speculation is what you think was going on and what you think happened. And sometimes it's okay to speculate but you need to let people know what's your opinion and what the facts are. And if you don't know the cause of the bug, it's important not to guess at the cause of the bug because you don't wanna have engineers spending a lot of time chasing down a false lead.

So now, let's take a look at the second key part of a bug's description, steps to reproduce the problem. Now the goal with steps to reproduce is to think of what it would take if you had a new machine and you got it out of the box. What would you need to do to make this problem occur? When you're writing up steps to reproduce you wanna put yourself in the engineer's shoes and think about what it is they're going to need to know.

You want to add include lots of information. It's much better to have too much information than to have not enough information. You wanna anticipate the types of questions they're likely to ask you. You wanna minimize the amount of back and forth between you and the engineer required to solve the problem. Every time an engineer stops and asks you a question it means they put down your problem and work on someone else's problem.

You can't make any assumptions about what people will know about your situation or about your particular piece of software. It's important to be very specific. If you're writing about a particular program, instead of using terminology from your application or your business like debits or credits. You would want to describe what menu items to choose and what controls to click.

And when you're describing what you did it's important to describe what you did in detail and not just the high level action you performed. For example, say that you wrote open this file. Well there are many ways to open a file. And when opening the file works you get the same end result.

But, if something goes wrong this could've gone through different code paths. So it's important to describe what it is you did. For example, if you could double click on a file or you could click on a file and choose open, or you could run the open command in terminal or you could file menu and choose open, so write down which of these actions you actually took. In this case we could say double click on a file.

When you're writing up your steps to reproduce it's important to describe what machine or system is necessary to reproduce the problem. Is this a problem that will only occur on a PowerPC or only on a Intel machine or on both? Is this a problem that requires a 64 bit mode or is this a problem that also occurs in 32 bit, on 32 bit machines.

Now, Apple now makes software for Windows as well as Mac OS X. And it's important to describe which operating system you need to use to reproduce the problem. For example, if you're using Safari or iTunes is this a problem that only occurs on Safari or iTtunes or Mac OS X or only for Windows, or both? If you have a PowerPC application is this a problem that only occurs under Rosetta or does it occur when running on a PowerPC machine as well? And what about your home directory? Does this require specific type of home directory for the problem to occur? Does this problem occur on a regular home directory? Is this a problem that only occurs when you're using a removable home like on a fire wire drive or an iPod? Is this a problem that only occurs when you're using a network home directory? What about you user type? Is this a problem that occurs with standard users or admin users? Now on Leopard we have guest users and we have, what about when you're using parental controls? Do you need to use parental controls to reproduce this problem? Is this a problem that requires you to use fast user switching to reproduce? I'm gonna tell you two stories that will illustrate the importance of detailed steps to reproduce when writing a bug.

First is, a problem I ran into when using the installer. One time I was installing some software and I would always get to the same point in the installer and the installer would hang. I thought this was odd and so I wrote up a bug. I included in the bug a sample of what the installer was doing when the hang occurred. And I attached the package I was installing which reproduced the problem.

And I've described exactly how far through the installer I got. And I sent this bug over to the installer too. And the installer engineer looks at my problem and he tried to reproduce the problem and he couldn't. And he called me up and he said Paul can you help me out here? Can you come show this to me? So I said fine. He came over to my office. And the installer engineer sat and he watched me reproduce the problem.

And then I watched him not reproduce the problem. And we repeated this process for about 15 minutes. We couldn't figure out what was going on. And then I remembered that I was using full keyboard access to navigate the installer. That is, I pressed tab to highlight a button and spacebar to activate a button and he was using the mouse. So he was pointing and clicking. So when you're writing up your steps to reproduce, if you're, if you're using any accessibility features, if you're using full keyboard access, include that information in the bug.

And now, the second story how many of you have friends or family members who ask you for help with computers? Alright, so, my dad does this a lot. And I've tried to explain some of these ideas to him. And he's gotten to understand them pretty well. And so, he ran into a problem with Safari.

And he sent me a screen shot of the Safari window, which showed the problem. And he sent me the URL and I opened up the URL on my machine. And I looked at the page and it looked fine. And it didn't match his screen shot. And I phoned up my dad and I checked with him. I said what version of Mac OS X do you have and what version of Safari do you have? And I made sure we both had the same version.

And we were talking about this for a while. And then I remembered something. My dad's old. And he wears glasses. And so what had he done? He had turned on the minimum font size preference in Safari. And, as soon as I turned that preference on I too saw the problem. So, it's important when you're writing up your steps to reproduce to include any preferences that you've changed from their default values.

Now let's move onto the third part of a bug's description regression. What does this mean? Well this is when does a problem occur and when doesn't it occur. This is a problem that will occur on particular builds of Mac OS X, for example a problem that occurs on Leopard and not on Tiger.

Do you have any fire wire or USB or any bluetooth devices attached to your machine? If you remove these devices does the problem go away? If so, add them back one at a time until you can figure out which device caused the problem and include that information in the bug.

And what about this problem? Is this a problem that I can see if I log out and I log back in? What if I restart the machine? Does this problem still occur? If I put the machine to sleep and wake it up does that have any effect? What about if I turn the machine off and power it back on? Next it's important to describe what you expected to see and how that differed from what you actually saw.

Say you wrote up a bug and said I was using this program and I saw a purple triangle. And the engineer reads the bug looks at it and says. Of course you saw a purple triangle that's what he was supposed to see. This is great behaves correctly and sends it back to you.

And maybe, instead of a purple triangle you expected to see a green triangle or maybe a purple sphere. So instead, write in the bug what you expected to see and how that differed from what you actually saw to make it clear to the engineer why you thought that was a problem.

In the final part of a bug's description is the workaround. If your problem has a work around it's important to describe that in the bug. This does two things. First, it might help the engineer understand the cause of the problem. And second, if a work around is present you can let the engineers know that this problem may be less important to you than another problem for which no work around yet exists.

Once you've done writing up your bug description it's important to read over the bug and make sure that it makes sense to you. Is it in the right order? Do you have all the necessary information in the description? If there's someone else around have them look at your bug and make sure that it makes sense to them if they were the engineer. Now let's take a look at the third part of a good bug report, data about the problem.

When you're writing up a bug report there's often a lot of useful information you can attach to your bug. And depending on what type of problem it is you'll wanna include some of this information. If you were to run into a crashing bug you would wanna include the crash log. Remember that crash logs can appear in two places.

If this is a per user application like mail or finder or Safari then the crash log will appear in the library folder inside your home directory. If this is a system daemon like window server or MDS then the crash log will appear in the library folder at the root level of your hard drive.

Now, when it comes to crash logs you'll see on Tiger and earlier inside your library folder there's a log folder and a crash reporting folder and the files will named application name.crash.log. And the crash will be appended one after another. But this has changed in Leopard. Now we have individual .crash files for each crash. And in your crash reporter folder you'll see files named application name_date-process ID_ host name.crash.crash. This makes it much easier to find just the crash you want.

Now if you want to take a look at the console log to get additional information, for example if you run across a program that's thrown into exception this information is usually written in the console, you'll want to look here. On Panther and Jaguar in your library log console folder you'll see a folder with your user name and then a file called console.log. And then in Tiger instead of your user name you'll see your user ID.

But, once again, this has changed on Leopard. There is no longer a console log file. Instead, we use the apple system logger facility. And if you want to see what you receive from the console log you use the syslog command. And you say syslog -k Facility com.apple.console. There are a couple of other logs that are very helpful depending on the type of problem. If you run into a kernel panic, of example, the information about the panic will be stored in library logs panic.log. And the system log file in /var/log, contains a lot of helpful information which, programs will often write out should the run into any error condition.

If you run into a problem related to syncing there are two log files that you want to attach. The first is in your home folder in the library folder and in the log folder it's a sync folder. So second in library applications report is a sync services folder. Attaching this information can be very helpful when debugging sync problems.

Now if you run into any performance problem, that is something is slow or it's hanging or it's unresponsive, then it's really helpful to include a Shark profile with your bug report. And with Shark you can profile just the application or you can profile the entire system, if it's an interaction between multiple applications. If you don't have Shark installed you can use the sample command line tool. But Shark profiles are much more useful, contain a lot more information for engineers to analyze.

And then new in Leopard is this tool called Xray. And while Shark is good for recording information about slow downs or hangs, actually it's good for recording information about other types of system activity like file system usage or memory usage. So if you wanted to track down what leaks were occurring you could use Xray. And another really handy feature of Xray is the UI recorder.

So you can record what's going on, on your screen when the problem occurs. And when you attach this Xray document to your bug report the engineer can see exactly what you saw on his screen and what you saw on your screen. This will completely clear what the problem is.

There are a couple of command line utilities, which can be helpful depending on what type of bug you see. The fs_usage command lists all of the file system activity. And the lsof command lists all the open files on your machine. This is very helpful if you run into a disk that you can't eject or a volume you can't un mount. And if you have this older utility here Sampler don't use it. Instead use the sample command line tool if that's all you have or use Shark. In fact, if you have Leopard we don't even ship Sampler any more. Sampler is now an Xray template.

You know, people often say a picture is worth a thousand words. And when it comes to bugs this can be true. What type of picture to you include in a bug? Well you include a screen shot Why do you wanna include a screen shot in a bug? Well there are a couple of reasons.

First of all, if you have any sort of rendering or redraw problem, these are often very hard to describe or they can be very subtle. And it's much better to include a picture, which shows what you saw rather than trying to describe what you saw. As I mentioned earlier you run into something, you don't know what it's called, anything where the terminology is unfamiliar including the screen shots is really helpful.

So, how do you take a screen shot on Mac OS X? Well starting with Tiger you can use the preview application. And if you go to the preview application and you look under the file menu there's a grab sub menu. And there's three items there, which allow you to take a picture of a selection of a screen, a particular window, or the entire screen after a time period. And this one's really helpful, if you run into a problem that requires you to hold down other keys and part of the mouse and so you couldn't pass a keyboard shortcut.

And when it comes to keyboard short cut there's, of course, the old standby of command shift three, which takes a picture of the entire screen. If you push command shift four you've got a cross hair curser and you can drag that to select the part of the screen that you want.

And if after pressing command shift four you hit the space bar your curser will change to a camera icon. And you can click on the particular window or menu item you wanted and you'll get a screen shot of just that. And there's some new screen shot features in Leopard too.

Before we get to that I wanted to mention that if you push the control key when you're taking the screen shot instead of being saved to a file on your desktop it'll be copied to the clip board so you can paste it into an image editing program or into a bug, into a bug report or so on.

So the new Leopard features, well, one of them is after you push command shift four and after you start dragging, if you push the space bar, they'll allow you to reposition your selection. So, you don't have to start from scratch, cancel your selection and redo it. You can just move it let go of the space bar and then continue your drag again.

And if you run into a situation where you don't have access to the keyboard or you wanna take a picture of a remote machine or the problem's occurring say in log in window where you're not even logged in as a user. If you SSH into your machine you can use the screen capture command line tool and say screen capture myfile.png and it'll save that wherever you'd like.

Now sometimes a picture isn't enough to illustrate your problem. And in this case a movie can be helpful. And there's two ways you can get a movie. The first is to use a third party utility like Snapz Pro, which will record what's going on in your screen. The second is to go ahead and grab your camcorder and film the screen. And then you can input that into iMovie and export it as QuickTime and attach that to your bug.

Now, sometimes you can't take a screen shot for other reasons. For example, your machine is hung or frozen or unresponsive. Or maybe it's a problem with DVD player, which prevents you from taking screen shot in the normal way. In this case, go ahead and grab your digital camera.

Turn off the flash, point the camera at the screen, take a picture and attach that to your bug. Now if you're taking a screen shot of any dialogue or any Safari window with a URL or any error message, it's important to include the text from that screenshot in your bug report. So there's two things, first it allows people to search for that particular error in a bug. And the second is when you do this it minimizes the chance of a misunderstanding or a transcription error if someone else transcribes it for you.

Let's take a look at an example of improving a screen shot. So here we have a screen shot and we see these two buttons and they don't quite look the same. One of them is a brush metal button and one of them is a regular aqua button. After you receive this bug you might be a little confused to what's going on here unless you're really sharp eyed and you notice that, you remember that this is actually from address book.

So, a better screen shot here would be to include a screen shot of the entire screen. And here we know that those two buttons came from address book. And it's clear, but this is a lot of extra information. And we don't need the entire screen to illustrate the problem.

And there could be additional things going on in the background, which are distracting or might be misleading. So, instead, it would be good to pick a screen shot of just the window of address book. And we can do it like this. Using command shift four and then the space bar.

And this is a really good screen shot. But if we wanted to improve this screen shot even further we can take this open it up in image editor and circle the button, which is the problem. And then it is absolutely clear to the person reading the bug what we thought the problem was.

Now there are couple of things. Well I've just described a lot of information you can include in your bug report. But there are a couple of things you don't want to include in your bug report. The first is any sort of confidential information, if you have trade secrets or if you have social security numbers, don't include that information in your bug report.

The second is third party applications. So if you have an application you're using that you didn't develop and it's necessary to reproduce the problem, don't include that in your bug report. And certainly don't include your personal serial number for that application in the bug report. And of course you don't have to include all of this information in every bug. You want to include only relevant parts to your particular bug.

Now, let's move on to the fourth part of a bug report that is configuration information. So, what, here once again is an example of the type of configuration information you'd wanna include in a bug. Now if you would write this problem occurs on Mac OS X Tiger someone could read this and they would look at it and they'd say hum, what's Mac OS X Tiger mean to him or her? There are a lot of different versions of Tiger.

We have 10.4 through 10.4.9. And often we have different builds, for example if we release a new piece of hardware we'll have a new build on Mac OS X for that piece of hardware. So it would better to include more specific version information about Mac OS X. So, we could write Mac OS X 10.4.9 8P2137.

But the problem might involve more than just the version of the operating system. It might be specific to certain types of machines or certain pieces of hardware. So we could start writing more information. We could include what type of Mac book we have and what, how much memory we have, and what type of optical drive we have. But this is a lot of work and we might not get all the information we require. So the best way of providing configuration information is to attach a system profile to your bug report.

And there are a couple things to remember about your system profile. The first is when you save it from system profiler to save it in SPX format and not RTF or text. This makes sure you include all the information and it'll also include excerpts from important log files. And the second thing to remember is that you wanna include the system profile from the machine in which the problem occurred and not necessarily the machine from which you're reporting the problem.

Now, if you're running Windows there is no system profiler application. But if you install QuickTime for Windows you get this handy program called QTinfo.exe. And if you open up QT info there'll be a screen that looks like this. And this has a lot of useful information about the hardware and software in your system.

So you can copy information out of there and include that in your bug report. Now, if you have multiple displays it's important to include information about your display set up in the bug. This is especially helpful if you have any sort of a resolution or redraw problem or if you have sleep or wake issues.

What information do you wanna include? Well first how many displays do you have? Second, are the additional displays in mirroring mode or are they in extended desktop mode? If you have a PowerBook, iBook, or MacBook, is the lid of this machine closed or opened? What is the physical layout of these monitors on your desktop? And what is the logical layout of them that is how does the display preference page think they're laid out? And finally, which of these displays is the menu bar on? Now if your bug involves a particular application, for example one of the applications that you're developing, you'll want to include that application with your bug report.

If you're writing a problem about a particular application it's important to include specific version information about that application. It's not enough to say I'm using the current version, or I'm using the latest version, or I'm using the version they shipped with my Mac. For example if you're into a problem involving Photoshop, you can't just say I'm using Adobe Photoshop CS.

You might need to say I'm using Adobe Photoshop CS2 9.0.1. And if you're using an Apple application introducing to the version number in the above box you can find the build number. So in the case of preview on your Leopard CD you can see previous 3.5.0 build 451.4.

Remember that versions of software not only change in software updates but they can change in security updates. So it's important to include specific version information above your application in the bug. Now, the third party software, if you're including your third party software and you need to makes sure that, excuse me, if you're, if your problem involved third party software like kernel extensions or plug ins or haxies or input managers what you wanna do is disable these items and see if the problem still occurs. And if the problem goes away then you know the problem was caused by a particular third party, a particular piece of third party software, and you can attach that to the bug or include that information in the bug report.

Alright, let's move on to reproducibility. This part's real easy. What is reproducibility mean? Well, this is a problem that occurs all the time, every time I do this particular set of actions. This is a problem that's intermittent. Does it only occur some of the time? Or is this a problem that I saw once and then I'm unable to reproduce.

Let's sum up the best practices for writing a bug report. So, we start off with the bug's title. We then include a summary of the problem. We'll include detailed steps required to reproduce the problem. We'll describe what we expected to see and how that differs from what we actually saw. We'll include regression information about where the problem does and doesn't occur. And configuration information about the machine on which the problem occurred. And finally information about any work around that's available and describe how reproducible the problem is.

Because this is an Apple session, I thought it would be helpful to include specific information about Apple applications. So, what do you do, for example, what do you need to know about reporting bugs to Apple? Well if you're reporting a bug that you encounter when using your own third party application, you have to assume that the people reading the bug report have never seen your application before. And they don't necessarily know what it does and they don't know your particular application's terminology. So as I mentioned earlier it's important to be specific in your steps to reproduce and describe menu items and controls instead of high level terminology specific to your application's domain.

If this is a problem with your application, for example you're Adobe or you're Microsoft, you need to make sure that we have access to your application to reproduce the problem. And if your piece of software requires a dongle or serial number or an activation key of any kind or some sort of user name or password, in your bug report to Apple provide that information. And if you're providing a copy of your application make sure that it's not a time limit or a trial version of your application which might expire before the engineer gets a chance to finish investigating and solving the problem.

So we have three Apple applications I'm going to cover. The first is Xcode. Now, you're all developers here, which means you probably spend a lot of time in Xcode. So what information do you need to include when you run into a bug with Xcode? Well the most helpful piece of information is your project file, and, if you can attach that to the bug then that's great. But sometimes you can't attach your project file. It might be too big or it might have confidential company information in it. In that case it's important to include whatever project data you can.

For example, if you can write a test application, which demonstrates the problem, then go ahead and attach that to the bug. Next if you have a particular unit test attach that to the bug. A failing unit test is really helpful. It's very specific. If you can write any sample code at all which demonstrates the problem, even it say its only three lines. Then include this in the bug.

And finally, if your problem occurs only with particular sets of data then attach this data to the bug report and mention that it requires this data to reproduce the problem and it doesn't always occur. When you're writing bugs against Xcode it's important to include all kinds of evidence. You want to include circumstantial evidence especially If you run into any sort of intermittent problem. Even if the engineer can't reproduce the problem they might be able to use this circumstantial evidence to prevent the problem from occurring in the future.

When, remember also that Xcode changes at a different schedule that Mac OS X itself. So it's important to include information about what version of Xcode you're using. You can go to the Xcode menu and choose a better Xcode. And you'll get information about the version of Xcode and its underlying frame works.

If you're using developer tools other than those provided with your Xcode DVD for example from think or Darwin ports, or if you've compiled your own compiler it's important to include specific version information about your version of GCC and your version of GDB and LD in your bug report. If you run into any sort of compilation or leaking problem then including the build log from Xcode is key.

Xcode will create two types of temporary files. The first is a caches file in your library caches Xcode folder. Try moving the file aside. If the problem goes away then it's likely that a corrupt cache file was the cause of your problem. And attach that to the bug if you can.

The second thing is Xcode creates a build directory where it puts intermediate representations like .o files. Try moving this aside. If the problem goes away, once again it was likely caused by a problem with your intermediate file. And if you can attach that to your bug report that's great.

If you're running on Tiger you could try disabling the 0 link feature of Xcode and see if the problem goes away. If it does, include that information in your bug report. Now, Xcode 3 on Leopard no longer has your link so you don't need to worry about this.

The second Apple application or Apple technology I'm going to talk about is Java. What is it you need to know about reporting Java bugs? Well, if you run into a Java application that hangs, you, getting a sample of Shark profile will tell you information about the Mac OS X threads but you're probably also interested in information about the Java threads. If you go to the terminal and you type kill -QUIT in the process ID of the Java process you'll get a SATrace of the Java threads.

This will appear in different places depending on how your application was launched. It could appear in terminal. It could appear in the console log. If you're using Safari and you've enabled the bug menu, as we'll talk about in a minute you can see stuff in the Safari Java console.

If you're running this from Xcode this information might appear in your Xcode run log. Now, when a Java application crashed on Tiger in addition to your regular crash log you would see a Java native crash log in library logs Java. And you would see JavaNativeCrash_pid and the process ID of the process that crashed that log. And so you would want to attach that as well as the regular crash log. But now, on Leopard you don't need to worry about that any more. In your regular crash log there'll be information about the Java threads as well as the native Mac OS X threads.

If you're using a preview version of Java, it's important to include that information in your bug report. And you can prefix your bug title with the version of the Java developer preview you're using. And when you're using a preview it's important to regress this bug. Is this a problem that only occurs with a preview or does it occur with the shipping version as well? When I say version of Java it's not enough to say I'm using java 1.5. You wanna include the full version of Java you're using. In this case Java 1.5.0_11.

But in fact this here is not the full set of version information for Java. If you go into the terminal and you type java -version, you'll get all this information. So, if you're writing a Java bug, it's best to do this and paste this information into your bug report. That way the Java team knows exactly what version of Java you were using when you saw your problem. Now, if you have a JUnit, unit test that reproduces the problem then it's really handy to attach that to you bug. This says two things.

First, it ensures that the Java team saw exactly the same problem that you saw. And second, it's possible that they'll include this unit test in their test suite, which means once they fix this problem it won't reoccur in the future. And finally the last piece of Apple specific information is about Safari.

So, if you run into a Safari bug, one of the things you might wanna do is look at the web page and other web browsers like Firefox or Opera, or Camino and see if the problem goes away. If the problem goes away then perhaps what the site is doing is using browser detection and preventing different content to different web browsers.

So, you go into the terminal an type this command, defaults write com.apple.Safari IncludeDebugMenu 1. And quit Safari and re launch it. And now at the end of your menu bar you'll see this debug menu. And you can tell Safari to go and pretend that it's another browser like Netscape, or Firefox, or Internet Explorer for Windows. So go back to the site and see what happens.

Now, suppose that the problem goes away completely. In this case you know the site's using browser detection. And you can go ahead and write up a bug. The second thing you can do is what happens if the problem changes? For example, they wouldn't let you into the site at all but now they let you into the site and it doesn't work properly. Well this could indicate the site is using browser specific JavaScript or HTML like the old document.all dom method pre dom method.

The Safari team works closely with website developers to ensure that websites are written using web standards therefore will work with all modern web browsers. So, if you run into either of these situations go ahead and write up a bug even when it's a bug with the website itself and not with Safari.

Now if you run into a problem with Safari and you're using a particular plug in it's important to include specific version information about that plug in. Another handy thing you can include in bug reports is a web archive. Web archive ensures that the Safari engineers see the same web page that you saw. And this is particularly important for new, for websites that change frequently like new sites or blogs.

Another handy thing you can do is go to webkit.org and download the nightly build a WebKit. And you can see how the sit looks in WebKit. And if the problem occurs in Safari but doesn't occur in WebKit then there's a good chance that I'll be fixed in the next version of Safari.

But what if the opposite happens? Say the site in question that you're developing looks great in Safari but doesn't work in WebKit. Well, in this case you should definitely file a bug. It's important that sites that worked in Safari continue to work in Safari. Safari team treats regressions as one of their top priorities.

When you're filing a bug about a particular site it's important that you include the full URL to the page in question, which demonstrates the problem and not just the name of the site. If the site requires a user name or a password to access here's what you should do.

If this is your own site that you manage then go ahead and provide this information to the Safari team. But if this is someone else's site like if it's your bank's site or your broker's site, don't include your information in the bug report. But, instead, provide contact information for the financial institution so the Safari team can get a hold of them and get a test account.

What about fire walls or proxy servers? Well, if you're running a fire wall or proxy server and that's causing problems then you'll wanna include specific information about the platform and version of the software in your bug report. And finally the gold standard of a Safari bug, what's the gold standard of the Safari bug? Well, it's called a reduction. What's a reduction? A reduction is the smallest part of a web page necessary to demonstrate the problem.

How do you make one? Well you take a look at the source of the web page and you start removing pieces. When the problem goes away you start adding pieces back. Now, it's certainly not necessary to either test on a WebKit nightly or include a reduction with your Safari bug report. You can still file a bug. But if you do, do this then you're making the Safari team very happy and we certainly appreciate it.

Now, last month it was Memorial Day and some of you hopefully had the weekend off and maybe got to enjoy a nice barbecue. And suppose being a Mac geek you wanted to show off your Mac to your friends. And you said okay, you know, check this out we have this new program it's called iChat and we can have these video conferences and it's super easy and it's great. And you go and you say you wanna have a video chat with your friend Maude who is in Montana. And you open up iChat and you try and chat with Maude in Montana and the chat doesn't work.

Oh no. And you feel really bad because your friend thinks you don't know what you're doing. And you're like oh, okay. So, what we have now is a good story. How is it we can transform this story that I'm telling you into a good bug report? Well let's take a look at what happened how we can transform that into a bug.

First thing we wanna think about is the bug's title. And notice the title of the bug I've written here. It says, iChat video chat failed with QLink XJ47 router. G Because, this problem occurred at someone else's house and not at my house, and what was different about their house? Well, they had a different type of router.

And notice how I've prefixed the bug with the version of Mac OS X I was using. Next, do include configuration information because this is about a video chat, I'm including configuration information about two machines, my machine, the MacBook and Maude's machine the iBook G4 who happens to be using a fire wire iSight.

And because this is a different type of router I'm including the version information for the firm ware in the router. And I've done some regression on this bug. I know this works at home all the time because I talk to Maude on a regular basis. And it works with my LinkSys router. And I know that it works with the DMZ both on and off. And I know it works if I use port forwarding. And I'm including all this information in the bug.

And there's a couple of handy types of files you could include in this bug report. For example if you're using Mac OS X 10.4.7 or later when a chat connection attempt fails in audio video chat you'll see a report bug to Apple sheet come up. And you can disclose that sheet, copy the information about the error and paste that into your bug report. And I wanna include information about what type of accounts I was using, for example .mac accounts or AIM accounts or Jabber accounts.

So let's sum up what we've talked about today. Well, we've talked about what is a bug and why we file bugs. And we've talked about all the parts of a good bug report. And we've used a story, a real world example to illustrate how we would apply this information to create a bug.

So, while great bug reports will help you make great software. And when you have great software you have happy customers. So, I encourage you to write a bug today or either take this information that you've learned, find something that's bothering you because there's gotta be something that's bothering you. You've got a beta version.

And write a bug report today. And every but report you write you'll get better at it. Practice makes perfect. And if you apply these best practices it helps improve your bug report writing skills. So, when you write a bug report you will get the kind of action that you were hoping for.

Thank you very much. Now, before we go I wanna include a couple of handy resources that you might find helpful when writing bug reports. The first is of course our Bug Reporting Best Practices document on the developer.apple.com web site. There's a tech note you might find handy, tech note 2124 called Mac OS X Debugging Magic.

If you're writing any sort of low level bugs you'll find this very helpful. The Apple Publication Style Guide is a good list of information about how we describe things. Of course, the Apple Human Interface Guidelines describes the controls and other user interface elements you'll see. You'll wanna get the chat tools from developer.apple.com/tools/download.

You might find Amit Singh's Mac OS X internals book very helpful in gaining understanding in how the system works. And when it comes to the writing part there's a handy blog called Good Words Right Order, which takes a look at analyzing writing. And of course the Chicago Manual of Style if you're really interested in more about how to write effectively, and now the one with the answers to all of your questions Amy Louv.