Topic: Best Practices

Best Practices:
1 : Bug Header Information
      1.1 : Product/Component
      1.2 : Classification
      1.3 : Reproducibility
      1.4 : Version/Build Number
2 : Bug Title & Description
      2.1 : Title
      2.2 : Description
3 : Additional Information Requirements (General)
      3.1 : Configuration Information (System Profiler Report)
      3.2 : Crashing Issues
      3.3 : Kernel Panics
      3.4 : Hanging/Performance Issues
      3.5 : Screen shots
4 : Contact Information
5 : Apple Product-specific Information Requirements

Bug Header Information:

1.1 : Product/Component:
Choose the product or software component where the problem originates.

1.2 : Classification:
Setting the appropriate classification for the bug helps us properly classify the priority of the problem.

Following are the Classification options and definitions:

    * Security: Potential security exposures.
    * Crash/Hang/Data Loss: Bugs which cause a machine to crash, resulting in an irrecoverable hang, or loss of data.
    * Performance: Issues that reduce the performance or responsiveness of an application.
    * UI/Usability: A cosmetic issue, or an issue with the usability of an application.
    * Serious bug: Functionality is greatly affected, and has no workaround.
    * Other bug: A bug that has a workaround.
    * Feature (new): Request for a new feature
    * Enhancement: Request for an enhancement to an existing feature.

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

1.4 : 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.



2. Bug Title & Description


2.1 : Bug 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 which 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:

    * Be objective and clear (and refrain from using colloquialisms/slang)
    * Include keywords or numbers from any error messages you may be receiving
    * Avoid using vague language, such as "failed", "useless", "crashed", etc....

The following examples demonstrate the difference between a non-functional title and a functional title:

    Example 1:
        Non-functional title:
    Application Crashed.


        Functional title:
    8J2135: Finder crashed connecting to iDisk

    Example 2:
        Non-functional title:
    iMovie completely fails.

        Functional title:
    iMovie 6.0.1 fails with error when exporting to QuickTime




2.2 : 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 a more descriptive summary information.

        * Provide what happened, what you were doing when it happened, and why you think it's a problem
        * If you receive an error message, provide the content of the error message (or an approximation of it)
        * Provide specifics and refrain from using vague language or colloquialisms.

    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.

    Example 1:
        Non-functional description:
    When printing, nothing happens. Application doesn't work.

        Functional description:
    Print Menu item enabled, print dialog box appears, print button enabled, but progress dialog box doesn't appear.

    Example 2:
        Non-functional description
    Safari is slow.

        Functional description:
    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. Note: Be very specific and be sure to provide details, opposed to high-level actions.

    Important points to note when providing steps to reproduce are:

        * When does the problem occur?
          - Does it occur after log-out?
          - Does it occur after relaunch?
          - Does it occur after shutdown?
        * Where is the home directory that you're working from?
          - Is this a regular local home directory?
          - Is this a portable home directory (on an external drive)?
          - Is this a network home?

        * What type of user is it that is in question?
          - Is it a standard user?
          - An admin user?
          - Is it a managed client user?

        * Be sure to include any Accessibility features that you're using (such as VoiceOver, keyboard navigation), as well as stipulating whether you're using the keyboard or the mouse to navigate.

        * Include information about any preferences that have been changed from the defaults.

        Example:
            Not-functional:

            Opened a file.

            Functional:

            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.



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 listing of essential files that are frequently required and stipulates the scenario in which each respective file is needed.

    * Include a system profiler report
    * If reporting a crashing bug, a   Crash Log is required
    * If reporting a kernel panic, a Panic Log is required
    * If reporting a hang, freeze, or performance issues, a sample and/or Shark profile is required
    * If reporting an error dialog message or UI bug, provide screen shots

3.1 : System Profiler report (.spx file):
To obtain a full System Profiler report, select "About This Mac" from the Apple Menu and click the "More Info" button. This automatically launches the System Profiler application. The System Profiler Report

From the System Profiler menu, select File -> Save As, and select:

File Format: System Profiler 4.0 (XML)

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).






Edited by moderator - 06May2007 at 10:45pm