Bug Reporting Best Practices

Welcome to the Apple Developer Bug Reporting Best Practices page. This page provides information regarding the best means in which to file a bug report. If after reading the Apple Developer Bug Reporting Best Practices you still have a question, please contact us.


1. Bug Header Information

Apple Developer Bug Reporter Header

i. Product

Choose the product or software where the problem originates. If these specific details are not provided, choose “Mac OS X” or “Other” in the product list.

x. Classification

Setting the appropriate classification for the bug helps us properly classify the priority of the problem. The following are the Classification options and definitions:

ii. Reproducibility

Let us know how frequently you are able to reproduce this problem.

iii. Version/Build Number:

Provide the version and build of the OS or application. To obtain this information in Mac OS X, select “About this Mac” from the Apple menu. Next, click on the version number listed under “Mac OS X.” You will then be able to view the build number.

Back to Top

2. Bug Title & Description

i: Problem Report Title:

The ideal problem title is clear, concise, succinct and informative. Note: This field is limited to 80 characters. The ideal title includes the following:

  1. Build or version of the software or OS on which the problem occurred
  2. Verb describing the action that occurred
  3. Explanation of the situation that was happening at the time that the problem occurred
  4. In case of a crash or hang, include the symbol name

When creating a title, we also recommend the following guidelines:

The following examples demonstrate the difference between a non-functional title and a functional title:
  Non-functional title Functional title
Example 1 Application Crashed 9C7010: Finder crashed connecting to iDisk
Example 2 iMovie completely fails iMovie 7.1.1 fails with error when exporting to QuickTime

ii: Description:

Include a Summary, Steps to Reproduce, Expected Results, Actual Results, Workaround, and Regression/Isolation.

Summary:

Recap the problem title and be explicit in providing more descriptive summary information.

Instead of using descriptive words or phrases when something “looks bad,” “has issues,” “is odd,” “is wrong,” “is acting up,” or “is failing,” be concise and describe how something is looking or acting, why you believe there is a problem, and provide any error messages that will support the problem being reported.

  Non-functional Functional
Example 1 When printing, nothing happens. Application doesn’t work. Print Menu item enabled, print dialog box appears, print button enabled, but progress dialog box doesn’t appear.
Example 2 Safari is slow. Safari is slow allocating JavaScript arrays. (Also provide a Shark sample and sample JavaScript.)

Steps to Reproduce:

Describe the step-by-step process to reproduce the bug, including any non-default preferences/installation and the system configuration information. Note: It is better to include too much information than not enough, as this minimizes the amount of back-and-forth communications. Be very specific and be sure to provide details, opposed to high-level actions.

  Non-functional Functional
Example Opened a file. Double clicked on a file to open it.

Expected Results:

Describe what you expected to happen when executing the steps to reproduce.

Actual Results:

Explain what actually occurred.

Workaround:

If you have found a workaround for this problem, describe it.

Regression/Isolation:

Note any other configurations in which this issue was reproducible. Include details if it is new to this build or no regression testing was done.

Back to Top

3. Additional Information Requirements (General)

Reports should include, at minimum, a complete System Profiler report showing pertinent configuration information (essential when reporting hardware-related issues). Additionally, the appropriate log files are essential when reporting crashing issues, kernel panics, or any other failures or error messages. Below is a list of frequently required files stipulating the scenario in which each respective file is needed.

  1. If reporting an issue with hardware, or general failure issues, Include a System Profiler report
  2. If reporting a crashing bug, a Crash Log is required
  3. If reporting a kernel panic, a Panic Log is required
  4. If reporting a hang, freeze, or performance issues, a sample and/or Shark profile is required
  5. If reporting an error dialog message or UI bug, provide screen shots

i: System Profiler report (.spx file)

To obtain a System Profile Report, select “About This Mac” from the Apple Menu and click the “More Info” button. This automatically launches the System Profiler application. Once the System Profiler application has been launched please follow the steps below.

  1. Select “Save” from the File menu
  2. Keep the format as “System Profile”
  3. Click the “Save” button
  4. Append the file to your bug report

A System Profiler report can also be obtained via Terminal using the following command:

/usr/sbin/system_profiler -detailLevel full -xml >mymachine.spx

This command will create a full System Profiler report, named “mymachine.spx,” which will open in System Profiler on another machine.

NOTE: A full System Profiler report provides vital information from the user’s hardware configuration (drive, audio, Bluetooth, graphics, and external hardware information), to networking configurations (including wireless, firewall, location networking, internal modem and volume information), to software configurations (including installed applications, extensions and fonts, frameworks, preferences, and access, console, error, install, mail, Software Update, and system log files).

ii. Crashing Issues

If a crash has occurred, a crash log is essential. To locate the crash log in Tiger (10.4) or later, check the following location:

~/Library/Logs/CrashReporter
/Library/Logs/CrashReporter

If you are not able to locate any crash report information in either of these locations, check the /var/log/system.log for any relevant error messages from “crashreporter” or “crashdump.”

iPhone crash logs can be obtained by following the instructions below.

NOTE: Only include one crash log per bug. If you’re able to reproduce the crash the exact same way each time and the crashing thread looks identical in every instance, only one crash log is required. This allows us to efficiently distribute the necessary information to Apple Engineering. In instances where the crash doesn’t look identical, file separate reports with one crash log submitted per bug.

* See TN2123 for information on the anatomy of a crash log.

iii. Kernel Panic

If a kernel panic has occurred, a panic log is required. Backtraces are saved to nvram, then copied to the panic.log file on restart. This file can be located in /Library/Logs.

* See TN2063 for information on the anatomy of a panic log.

iv. Hanging/Performance Issues

If you are experiencing a “hang” (includes freeze, spinning wheel, slowness), a sample of the application while it is in the hung state is required. A sample can be obtained by any of the below options:

Using Terminal

run ‘sample (Application Name) 15’

* The output can be attached directly to your bug report via the “My Originated Problems” section in the Bug Reporter.

Note: The application name must be typed exactly as the application is named; this command line is case-sensitive. After the sampling has been completed, Terminal will supply the file path to the location to which the sample analysis was written.

Using Activity Monitor

Note: more information about using “Sample” may be found on its man page, which can be retrieved by entering “man sample” in the Terminal window.

How to SSH into a machine (from another machine on the same network)

Providing the machine is not hung to the point that you cannot SSH into it, you can do the following from Terminal:

  1. ssh (IP address) -l (login account)
  2. top
  3. Identify the process taking a lot of CPU
  4. sample (process ID) 5
  5. cp /tmp/* ~/Desktop/
  6. Restart the machine and log in as the user you SSH’d into

Note: Use monospaced font for Terminal commands.

Shark:

You must have Shark installed to provide a Shark profile. Steps on how to obtain a Shark sample can be found here. For all of the means of gathering a sample, the sample file will appear on your desktop.

NOTE: If you have an older application called “Sampler” on your system, do not use this. A Shark profile provides more useful information.

v. Screen shots

Provide a screen shot when it will help clarify the bug report. In addition to providing screen shots for error or dialog messages, please type the text of the error/dialog message you are seeing in the description of the bug report (so that the message contents are searchable. If there are steps involved, a sequence of screen shots, or even a movie is always appreciated (but be sure to write down the steps associated with each screen shot).

It is useful to provide a screen shot when:

A screen shot can be captured in any of the following ways:
Description Shortcut
Save a picture of the entire screen shift-command-3
Save a picture of a selected area of the screen shift-command-4
Use Preview to capture a screen shot
  1. Launch Preview (/Applications/Utilities/Preview)
  2. From the menu, select File->Grab->(type of screen shot)
Use Grab to capture a screen shot
  1. Launch Grab (/Applications/Utilities/Grab)
  2. From the menu, select Capture->(type of screen shot)
Back to Top

4. Contact Information

Be sure to include current contact information. This will ensure that we’re able to correspond with you as we investigate your issue. This information can be updated by logging into the Member Center and choosing the “Update Profile” page, or by logging into the My Info page.

Back to Top

5. Apple Product-specific Additional Information Requirements

For bug reports filed against any of the following Apple products, product-specific information is required in addition to any generic information as stipulated above.

Xcode

When submitting a bug report against Xcode or any of Apple’s other developer tools, be sure to provide the following additional information:

Logs can be found at:
~/Library/Logs/CrashReporter/Xcode.crash.log

Note: Use of -save-temps leaves a preprocessed source file on the disk with the following file naming convention:

Java

When submitting a bug report against Java, be sure to provide the following additional information:

Safari

When submitting a bug report against Safari or WebKit, be sure to provide the following additional information:

Mail

When submitting a bug report against Mail, be sure to provide the following additional information:

iChat

When submitting a bug report against iChat, be sure to provide the following additional information:

In addition to all the above, provide any information regarding what you were doing around the time of the problem.

Audio

When submitting a bug report against audio, be sure to provide the following additional information:

Note: Version and build information can usually be found in the “About” window of the software installed, or in the product literature.

USB/FireWire

When submitting a bug report against USB or Firewire-related issues, be sure to provide the following additional information:

Additional information is required for issues specifically filed against AirPort and the iPod. See below for details of what information is required for each.

AirPort

When submitting a bug report against AirPort (for Client Mac or Wireless Base Station issues), be sure to provide the following additional information:

iPhone/iPod touch

You can file a report by logging into the Apple Bug Reporter from iPhone or iPod touch, as well as can update existing reports with information. Note, however, that because file upload is not supported, you will need to upload additional fils from a supported browser on your host system.

If you have experienced a crashing issue with an application on the iPhone, sync your iPhone with iTunes and check the following location on your host machine:

If you experienced a crash and you are not able to locate any pertinent crash report information, provide specific information including what you were doing, any URLs, or addresses that you were searching for at the time of the crash.

iPod

When submitting a bug report against the iPod product line, be sure to provide the following additional information:

Note: if you have an Apple iPod + HP sold by Hewlett-Packard (HP), HP, not Apple, provides support and service for Hewlett-Packard iPods.

iDVD

When submitting a bug report against an iDVD issues, be sure to provide the following additional information:

Back to Top