Do’s and don’ts when reporting bugs to Android Issue Tracker

Reporting a bug outside your company’s codebase is not as simple as DMing your colleague. This story listed do’s and don’ts for submitting bug reports, from the perspective of an Android engineer.

Motivation

I have been working in the infrastructure team to support the feature development teams at my company for over 2 years. Many of the issues are reported directly from my colleagues and one of my responsibility is to investigate those reports, root-cause the issue, and suggest actions.

Fortunately, most of the tools and libraries used in day-to-day Android development are all open-sourced. Kotlin, Gradle, a partial set of AndroidX libraries are hosted on Github whereas the Android Framework is hosted on cs.android.com. Most of them embrace issue triaging systems like Github, Android Issue Tracker, or Youtrack.

When I receive a bug report from my colleague, sometimes I find it difficult to further my investigation as the verbal description can be vague and confusing. I often end up requesting more details from the colleague.

In like manner, when reporting a bug to those open-source projects, we also want to be as helpful as possible for owners to examine the report and reduce the number of round trips in the conversation: Because the owners may live on the other side of the earth with opposite timezones and each round trip takes significantly longer than DMing your colleague.

❤️ Don’t take it for granted

Projects owners are the people with an unexpected difference:

• Maintaining the projects might be their personal responsibility, not their profession.
• There can be fluctuations in their personal lives affecting their availability. Think about COVID-19’s impact in 2020.
• They may live in a different culture or a different timezone.

The best advice here is to lower the expectation and don’t take it for granted. Bugs should not but still may be left unresolved for years. And even projects can be unattended for years. If this is an urgent bug that must be fixed, we could try to read the source code first and find a workaround ourselves.

We could escalate the issue to get attention, such as poking for an update by bumping the issue thread. Nevertheless, we should also know that escalation only gains attention but does not guarantee a solution.

🤖 Do leverage the template

Library authors may set up automation for raising an issue. Android Issue Tracker and Github provide the automation feature to specify an issue template. If such a template is automated and we see a checklist covering some of the topics mentioned in this story, please do follow them.

Even if such an issue template is not set up, try to act as if there is one.

👣 Do report the reproduction steps

One critical piece of information in a bug report is the reproduction steps. We don’t have to be grammatically perfect, but we do have to document exactly what we did. For example:

• The exact gradle command we ran.
• The exact button clicked in UI. With a screenshot if available.
• The exact stack trace we observed.

If the reproduction steps require code that spans over one page, a minimal sample project is would be recommended. Such sample projects should strive to include a minimal setup so that people on the other side can easily reproduce by a git clone. For instance, here is a sample project that I used to report the issue on Android Issue Tracker.

If creating a sample project still bothers you because you are scared of making too many clicks in the project creation wizard, check out this Kotlin Android Template for a quicker setup.

🌎 Do include the versions of your development environment

Versioning is a crucial topic for library authors. They are used to pinpoint the exact code execution of the bug. Reporting the versions of the specific framework or library when the bug occurred is hence exceedingly useful. If the bug was detected on an older version, we should perform a sanity check on the behavior of the bug on the latest versions. The bug might already be fixed in the latest stable version or development branch.

As libraries can depend on other libraries, it is also valuable to report debug information of our own development environment. Some of the well-known transitive dependencies include Android Gradle Plugin relying upon Gradle, Gradle relying on Kotlin, and Kotlin relying depending on Java. It is smart to report all possible versions, include those from OS, Gradle, Android Studio, Java, Kotlin, and the specific library that we are reporting to.

📝 Do read source code if available

No matter what the documentation says, the source code is the ultimate truth.
- Jeff Atwood, Co-founder of Stack Overflow and Discourse.

Sometimes there were illusional bugs which were reflecting my own ignorance. I don’t read documentation line by line, so a bug could happen just because I don’t follow the documentation.

There are other times where the documentation simply lags behind the source code. When the source code is available, and you get the exception stack trace, it becomes easier to know where to start reading the code. Trust me, the library author would thank you a million if you submit a PR to fix your own bug.

🔑 Don’t reveal your secret

If there is secret information related to your bug, do not share them publicly! Passwords, certificates, or other PII may put you or your employer at risk. If you are in doubt, please confirm with the authority and think twice before you hit “submit”.

👥 Don’t always submit a new bug report

When multiple people are DMing me the same bug, I know it is urgent but I need to update everyone in DM about the current status. Luckily, in most issue tracking systems, we have a more delightful way for prioritization:

• Android Issue Tracker allows people to star issues so that they have more signals for prioritization.
• Jetbrains announced in this video about including the number of votes in prioritization.
• Even on Github, we may react to an issue or a specific comment.

When you are about to submit a new bug report, consider searching for the existing issue. People may express the issues in a different way, so try to use keywords, stack trace elements, or even source filename to find existing reports. The owners’ time is more well spent on debugging rather than triaging duplicate issues.

🕒 Don’t leave it unattended

You may receive email notifications about an update on a bug report, or that email may get labeled as spam. Although most issue triaging systems are equipped with notification systems, try to bookkeep your issue reports so that you can follow up on any updates.

Reporting a bug is merely the first step. We might be involved in follow-up conversations like:

• More debug information is requested
• A temporary workaround will be suggested while the author is working on a longer-term correct fix.
• The owners may redirect the reporter to a different library for the fix.

Take away

This do’s and don’ts list are optional advice meant to improve efficiency and shorten the lifetime of a bug. Submit a bug report, in the end, is still a contribution and should be appreciated. You deserve to applaud yourself once a bug report is submitted!