How to Make an Issue Report

In the course of our lives as programmers, at some point we eventually will have to make an issue report against an open source project. Whether your issue report is a question, a bug report, or a feature request, filing a bug report is a deceptively complicated technical and interpersonal task. You’ll need to be prepared to spend a significant amount of time on your report; you’ll find that the decision of whether to file a report often comes down to the question of whether it’s faster to write an issue report or solve your problem another way. If you’re doing things right, filing a report may well not be the fastest way.

In this post, I’ll explain some of the key points of how to file an effective issue report. But first, I want to briefly explain the structure of open source projects and how they’re run.

How Open Source Works

Open source projects are kept in public code repositories, generally on GitHub. Although anyone can contribute code, projects are maintained by one or more maintainers who make up the “core team” of the project. These dedicated volunteers — maintainers are rarely paid, even those that maintain major projects — take on all the work of running the project: maintaining compatibility with other tools, fixing important bugs, adding features, reviewing community contributions, releasing new versions, and planning the direction of the project. Although community contributors are vital to open source, projects rely on their core teams to make sure that the most important work gets done (since much of that work is too difficult or not glamorous enough to attract community contributors to it).

When you file an issue report, it will fall to the core team to read it, respond to it, and decide whether and how to take action based on it. Above all else, when you make an issue report, remember that you are asking these volunteers to spend time outside their full-time day jobs and away from their families reading and responding to your report. Each issue report can potentially generate hours of work for maintainers. Being careful to communicate politely and include all the necessary information with your report will take you far in forming a productive relationship with the maintainers of the tools you use.

Types of Issue Reports

There are a few different kinds of issue reports, and different projects have different rules about where and how to make each.

• Bug reports provide information about errors or vulnerabilities you’ve found in a project. An example would be reporting an incompatibility between the tool you’re reporting against and another tool it’s supposed to play nicely with.
• Feature requests are requests to change the behavior of a tool. An example of this would be a request that the maintainers modify a test runner to allow tests to run in parallel. Making a feature request without offering to contribute code is a delicate proposition, since you’re effectively asking maintainers to volunteer their time to accommodate your use case. For this reason, it’s important to offer to help implement your feature if at all possible. (Remember, being too busy isn’t a good reason not to contribute — maintainers are busy as well. If you’re too busy to contribute, consider finding a different solution to your problem.)
• Questions about how a tool is used or how to achieve a certain result also appear commonly in issue reports. Many projects ask that questions be directed to a Google group, Slack channel, or mailing list instead of opening issue reports on GitHub.

Preparing to Report an Issue

Making an issue report requires significant preparation. Open source etiquette dictates a few steps you’ll need to take before opening an issue.

• Determine which tool is involved in your issue. If you’re working on a project that uses a large toolset — as most modern projects do — finding the tool that’s causing your problem or to which a feature would need to be added is usually a non-obvious task. Once you identify a tool, you’ll want to make sure the issue is with that tool and not with a dependency it relies on. Although mistakes in this aspect are quite common and maintainers are used to them, it’s polite to do as much research as possible into the nature of your situation before opening a report.
• Make sure your issue is an issue. After you’ve identified which tools are involved, you’ll need to make sure your issue is worth reporting. Is the feature you’re requesting already present? Is the bug actually a result of your misunderstanding of how the tool works? Are you using the latest version of the tool? Are your dependencies up to date? Are there idiosyncrasies in your development environment that would cause predictable failures? Are you using the right tool for the job? Google and StackOverflow are great resources for doing your due diligence.
• Find out what the problem is. At least formulate a hypothesis about what could be causing the bug, or how your feature request could be implemented. Again, this is often non-obvious and will require research. Check out anything that’s peculiar about your application and don’t forget to check whether the problem is caused by the way multiple libraries interact.
• Keep track of everything you tried. Have you tried changing your configuration? How? Did error messages change? What happens when you update your dependencies? Have you explored alternate approaches to solving your problem? Make sure to keep track of everything you try and save any output your program provides that might provide insights into what’s going on.
• Note which versions — of everything — you’re using. Many bugs are a result of incompatibilities between different libraries.
• Check existing issue reports. Duplicate reports make maintaining a project much more difficult. Additionally, comment threads on existing reports could help you resolve your issue without having to find a report. What you think is a bug might actually be a feature. Finally, you might find that a feature you’re considering requesting has already been added to the project — or rejected by the core team.
• Read and adhere to the contributing guidelines. Most projects have contributing guidelines going over everything from guiding principles, to coding practices the project adheres to, to compatibility requirements, to the information you must include with issue reports, to formatting your report. As you prepare your report, refer to the contributing guidelines — often found in a CONTRIBUTING.md file in the project’s root directory — regularly to make sure your report follows them as much as possible.

Writing Your Report

At this point you may have noticed that filing an issue report is no trivial task — and you haven’t even written the actual report yet. This, too, will take time. Here are some tips to help you out.

• Construct your narrative carefully. As you write your report, keep in mind that this may be the first time the maintainers have heard this issue. Consider the difference between, “I’m writing an iOS application using React Native. When I upgraded to Node 10, I noticed that <tool> caused my builds to break both locally and in CI due to a problem with the way Node handles ES6.” and “My builds started breaking when I upgraded Node.” The former will give maintainers a much better idea of what’s going on. At the same time, be mindful of what information may not be necessary. The problem described in these examples, for example, is probably not caused by an incompatible npm version, so that information would just give maintainers extraneous details to sort through.
• Include all the relevant details. This is where all the preparation work comes in. Include in your report dependency versions, information about things you tried, and any error output or warnings you’ve received. Although you’ll want to avoid including irrelevant information, going into detail about what’s happening is critical to helping the maintainers understand your problem. Make sure to include your hypothesis about what’s causing the bug or how to implement the feature you’re requesting.
• Link related issue reports. Is there a closed report on a similar issue that was never resolved? Is there an open pull request that might resolve the problem? If so, linking the issue (on GitHub, this is as simple as including a sentence like “This could relate to #443”) will help maintainers keep track of the work they’re doing on the project.
• Be polite. This should go without saying, but alas, as an open source maintainer, I can say with authority that it often does not. Remember maintainers are people with busy lives, and you’re asking them to donate their time and talents to help make your life easier. While you don’t need to include niceties, be careful to make sure your report is clear and concise and your tone is not too brusque or demanding. Additionally, refrain from reopening issues if a bug was tagged as wontfix (unless you’re submitting a pull request fixing it yourself) or a feature request was rejected previously.

Following Up

You’ve done your prep work. You’ve filed a clear, concise, friendly, and professional report. Your work is done, right? Wrong! At this point, you are still on the hook for answering followup questions and providing additional information the maintainers may need. If you’re particularly unfortunate, you may find out that, despite your best efforts, you’ve filed your report against the wrong project and you’ll need to report the issue again elsewhere!

Since, again, maintainers are volunteers, be aware that they may not be able to respond to your issue right away. Unfortunately, on some projects maintainers can take a month or more to respond to issue reports. If it’s been less than a couple weeks, nudging maintainers to respond faster is pushy and rude.

After filing your report, you’ll need to check your notifications regularly so you can respond promptly to questions the maintainers may have. Answering these questions may involve significant amounts of additional work, which you should be prepared to put in if you’re asking maintainers to put in their time on your issue.

Conclusion

If you take anything away from this post, it should be the following:

• Open source projects are maintained by volunteers who donate their time to solve your problems
• Issue reports should not be opened frivolously, and you should put in an effort commensurate with what you’re asking of the maintainers
• In addition to the technical challenges of filing issue reports, there are interpersonal factors at play that you need to be aware of
• Once you’ve opened an issue report, you’re responsible for responding to questions and comments until it is resolved

I realize you may have hoped for a shorter process here; nevertheless, I hope this post helps you get your problems solved and form quality relationships with other developers in your open source communities!