Bugs are an inevitable part of the development process. While they can be frustrating to run into, you can quickly get rid of these types of issues by identifying the problem you are encountering, reproducing it, and submitting a bug report. At Apple we offer an app and website called Feedback assistant for logging issues with Apple’s products or software.
You should always submit feedback for any bugs you encounter while developing on Apple’s platforms; after all, we cannot solve problems we do not know. But how do you make sure that the information you provide is helpful in solving the problem, rather than a dead end that fixes bugs? Here are some of our best tips to make sure your bug report is clear, doable and most importantly of all to fix.
Be clear and descriptive when you register a new bug report. Whether you provide specific feedback on a bug you encounter or general feedback, please describe your problem in detail.
This starts with a clear title that describes both the problem and the inflammatory factor. ‘Agenda appointments are missing’ tells the screener that there is a problem with agenda appointments, but not how or why. In contrast, “Calendar events on macOS 10.15.4 are missing after creating a quick event” provides more detail at a glance and may help identify duplicate bugs more quickly.
Tip: It’s often helpful for bug screeners to understand how problems affect app development. If you identify a problem while developing your app, include the name and version of your app in both the title and description fields – even if you can reproduce the problem in a sample project – and add a link to your Build an App Store record or a TestFlight.
When writing your problem, describe each step thoroughly – it’s often helpful to pretend that the person reading it has never seen the app or system you’re writing about. For example, if you write, “When I make an appointment in Calendar, it disappears in an instant,” the screener lacks enough detail to reproduce the problem. Do you make a calendar appointment using the Quick appointment button or drag to add a new appointment? How long does a moment last? Did the event disappear after multitasking or did you stay in the app?
Anytime a bug screener needs to pause and consider these kinds of questions, it reduces the chance that your problem can be solved quickly. Instead, think about ways you can describe your bug in detail, such as:
1. Click the Quick Event button in the Calendar app.
2. Enter an event with a title.
3. Press Return.
Actual results: the appointment appears in the right place on my calendar, but then disappears.
Expected Results: The calendar appointment should appear and remain in my calendar.
After completing your reproduction steps and the expected result, it is also worth considering additional factors that can affect the problem. Are you signed in to iCloud? Are accessibility settings enabled? Does the problem similarly reproduce elsewhere in the operating system? The more questions you can answer in the first report, the faster someone who reads it, can effectively triage it and transfer it to a correct team or person.
Add some visuals
If you can reproduce the bug and take video or a screenshot while it is taking place, this information can be invaluable to people looking to fix the problem. A screen capture can also help capture details that you may not have expected in the description field. If your issue is a UI issue, always include visuals.
Log the crash
Unfortunately, not all bugs are reproducible or have easy-to-follow steps. For more difficult cases, consider providing log information, such as a sys diagnosis: If you file a bug on your iPhone or iPad, you can use the Feedback Assistant app to automatically record one. If you report a bug through Apple’s web portal, you can install profiles that allow you to manually collect a sys diagnosis.
You can also provide additional logging that is relevant to the problem. For example, if you experience a crash, you can record your app’s crash logs. If you report a performance regression, you can record an Instrument track on iOS or iPadOS or a preview on macOS.
Improve bug reports with debug profiles and logging
Create a sample project
Having a problem developing an app? Consider isolating the problem in a small sample project that compiles. Not only can it help you narrow down the specific bug you’re facing, but it’s one of the easiest ways for Apple’s bug screeners and technicians to fix the offensive problem. If you can’t create a sample project, sample code is also helpful – additional information that can help mitigate the problem is valuable.
Escalate your report
If you are a paid member of the Apple Developer Program, Enterprise Program, or MFi Program and you have a technical issue with one of Apple’s platforms in a production release, consider submitting a technical support incident. This is a request for code-level support for Apple frameworks, APIs, and tools if you can’t fix a bug, have problems implementing a specific technology, or have other questions about your code.
Request technical support
More information about Feedback Assistant