{"id":115618,"date":"2020-06-09T16:17:30","date_gmt":"2020-06-09T16:17:30","guid":{"rendered":"https:\/\/developer.apple.com\/news\/?id=vvrgkboh"},"modified":"2020-06-09T16:17:30","modified_gmt":"2020-06-09T16:17:30","slug":"how-to-file-great-bug-reports","status":"publish","type":"post","link":"https:\/\/sickgaming.net\/blog\/2020\/06\/09\/how-to-file-great-bug-reports\/","title":{"rendered":"How to file great bug reports"},"content":{"rendered":"
<\/div>\n

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\u2019re running into, reproducing it, and filing a bug report. At Apple, we provide an app and website called Feedback Assistant<\/a> for logging issues with Apple\u2019s products or software.<\/p>\n

You should always file feedback for any bugs you find while developing on Apple\u2019s platforms; after all, we can\u2019t fix problems that we don\u2019t 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 \u2014 most importantly \u2014 fixable.<\/p>\n

Step by step<\/h3>\n

Whenever you log a new bug report, be clear and descriptive. Whether you\u2019re providing specific feedback around a bug you\u2019re running into or general feedback, describe your issue in detail.<\/p>\n

This starts with a clear title that describes both the issue and the inciting factor. \u201cCalendar events are missing\u201d tells the screener that there\u2019s an issue with Calendar events, but not how or why. In contrast, \u201cCalendar events on macOS 10.15.4 are missing after creating a quick event\u201d provides more detail at a glance and potentially helps identify duplicate bugs sooner. <\/p>\n

\n

Tip: It\u2019s 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 \u2014 even if you can reproduce the problem in a sample project \u2014 and add a link to your App Store record or a TestFlight build.<\/em><\/p>\n

\n

When writing up your problem, describe each step thoroughly \u2014 it\u2019s often helpful to pretend that whoever reads it has never seen the app or system you\u2019re writing about before. For example, if you were to write \u201cWhen I create an event in Calendar, it disappears in a moment,\u201d 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? <\/p>\n

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: <\/p>\n

1. Click Quick Event button in the Calendar app.<\/em>
\n2. Fill out an event with any title.<\/em>
\n3. Hit Return.<\/em><\/p>\n

Actual Results: The event appears in the right place in my calendar but then disappears.<\/em><\/p>\n

Expected Results: The Calendar event should appear and stay on my calendar.<\/em><\/p>\n

After filling out your reproduction steps and expected result, it\u2019s 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.<\/p>\n

Add some visuals<\/h3>\n

If you can reproduce the bug and capture video or a screenshot while it\u2019s 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. <\/p>\n

Log the crash<\/h3>\n

Unfortunately, not all bugs are reproducible or have easy-to-follow steps. For trickier cases, consider providing logging information like a sysdiagnose: If you\u2019re 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\u2019s web portal, you can install profiles that can help you manually gather a sysdiagnose.<\/p>\n

You can also provide any additional logging relevant to the issue. For example, if you\u2019re experiencing a crash, you can include your app\u2019s crash logs. If you\u2019re reporting a performance regression, you can include an Instruments Trace on iOS or iPadOS, or a Sample on macOS.<\/p>\n

Enhance bug reports with debug profiles and logging<\/a><\/p>\n

Create a sample project<\/h3>\n

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\u2019re facing, but it\u2019s one of the easiest ways for Apple\u2019s bug screeners and engineers to triage the offending problem. If you can\u2019t produce a sample project, sample code is also helpful \u2014 any additional information that can help narrow down the issue is valuable.<\/p>\n

Escalate your report<\/h3>\n

If you\u2019re a paid member of the Apple Developer Program, Enterprise Program, or MFi Program and you\u2019re having a technical issue with one of Apple\u2019s 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.<\/p>\n

Request technical support<\/a><\/p>\n

Resources<\/h3>\n

Learn more about Feedback Assistant<\/a><\/p>\n

Learn more about our privacy policy when filing bugs with Feedback Assistant<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

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\u2019re running into, reproducing it, and filing a bug report. At Apple, we provide an app and website called Feedback Assistant for logging issues […]<\/p>\n","protected":false},"author":2,"featured_media":115619,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[55],"tags":[],"class_list":["post-115618","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-apple-developer-news"],"_links":{"self":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/115618","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/comments?post=115618"}],"version-history":[{"count":0,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/115618\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media\/115619"}],"wp:attachment":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media?parent=115618"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/categories?post=115618"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/tags?post=115618"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}