How to file great bug reports
https://devimages-cdn.apple.com/wwdc...01A3/1024.jpeg
Bugs are an inevitable part of the development process. Though they can be frustrating to bump up against, you can help squash these sorts of problems quickly by identifying the issue you’re running into, reproducing it, and filing a bug report. At Apple, we provide an app and website called Feedback Assistant for logging issues with Apple’s products or software.
You should always file feedback for any bugs you find while developing on Apple’s platforms; after all, we can’t fix problems that we don’t know about. But how can you be sure that the information you provide is helpful for triaging the issue, rather than a bug-solving dead end? Here are some of our top tips for making sure your bug report is clear, actionable, and — most importantly — fixable.
Step by step
Whenever you log a new bug report, be clear and descriptive. Whether you’re providing specific feedback around a bug you’re running into or general feedback, describe your issue in detail.
This starts with a clear title that describes both the issue and the inciting factor. “Calendar events are missing” tells the screener that there’s an issue with Calendar events, 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 potentially helps identify duplicate bugs sooner.
Tip: It’s often helpful for bug screeners to understand how issues are affecting 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 field — even if you can reproduce the problem in a sample project — and add a link to your App Store record or a TestFlight build.
When writing up your problem, describe each step thoroughly — it’s often helpful to pretend that whoever reads it has never seen the app or system you’re writing about before. For example, if you were to write “When I create an event in Calendar, it disappears in a moment,” the screener lacks enough detail to reproduce the issue. Are you creating a Calendar event through the Quick Event button, or are you dragging to add a new event? How long is a moment? Did the event disappear after multitasking, or did you remain in the app?
Whenever a bug screener has to pause and consider this kind of question, it reduces the likelihood that your problem can get fixed quickly. Instead, think about ways you can describe your bug in detail, like so:
1. Click Quick Event button in the Calendar app.2. Fill out an event with any title.3. Hit Return.
Actual Results: The event appears in the right place in my calendar but then disappears.
Expected Results: The Calendar event should appear and stay on my calendar.
After filling out your reproduction steps and expected result, it’s also worth considering additional factors that could influence the problem. Are you signed into iCloud? Do you have any Accessibility settings turned on? Does the issue reproduce in a similar fashion in other places around the OS? The more questions you can answer in the initial report, the faster someone reading it can triage it effectively and get it over to the right team or person for a fix.
Add some visuals
If you can reproduce the bug and capture video or a screenshot while it’s happening, this information can be invaluable to people for troubleshooting the issue. A screen recording can also help capture details that you may not have thought to provide in the description field. If your problem involves an issue with the UI, you should always include visuals.
Log the crash
Unfortunately, not all bugs are reproducible or have easy-to-follow steps. For trickier cases, consider providing logging information like a sysdiagnose: If you’re filing a bug on your iPhone or iPad, you can use the Feedback Assistant app to capture one automatically. If filing a bug via Apple’s web portal, you can install profiles that can help you manually gather a sysdiagnose.
You can also provide any additional logging relevant to the issue. For example, if you’re experiencing a crash, you can include your app’s crash logs. If you’re reporting a performance regression, you can include an Instruments Trace on iOS or iPadOS, or a Sample on macOS.
Enhance bug reports with debug profiles and logging
Create a sample project
Running into an issue while developing an app? Consider isolating the problem into 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 engineers to triage the offending problem. If you can’t produce a sample project, sample code is also helpful — any additional information that can help narrow down the issue is valuable.
Escalate your report
If you’re a paid member of the Apple Developer Program, Enterprise Program, or MFi Program and you’re having a technical issue with one of Apple’s platforms on a production release, you should consider filing a Technical Support Incident. This is a request for code-level support for Apple frameworks, APIs, and tools when you cannot fix a bug, have trouble implementing a specific technology, or have other questions about your code.
Request technical support
Resources
Learn more about Feedback Assistant
Learn more about our privacy policy when filing bugs with Feedback Assistant
More...
