How to file an issue
Knowing how to file an issue with “the right information” may be the difference between it getting resolved immediately or never getting merged. We love community contributions so I thought it would be helpful to look at some of the common pitfalls to avoid.
Everyone would rather be doing something else than filing or triaging issues — it’s not the most fun part of being an engineer. It’s important to remember there are humans with feelings on both sides of an issue. The person filing the issue is frustrated because they just ran into a roadblock and the issue is the thing standing between them and getting their task done. I get the frustration but please remember that the issue isn’t the place to vent your anger. Think about the person reading and triaging the issue and remind yourself that venting will not help you in resolving the issue. Being disrespectful will only frustrate others.
Try to be succinct and clear
A common problem we see when working on issue triage is that many issues are written as stream-of-consciousness. Having details is good but let’s do our best to have details that help the issue triager. Let’s walk through some best practices when creating issues. When creating an issue, it’s important to have empathy for the reader and spend time working on the text so that it is succinct and clear. Fewer words are better! Choose your words carefully and consider how to best explain the problem to someone without context.
Don’t assume a shared context
Another common pitfall I see is that the issue author assumes that the person triaging the issue has the same context surrounding the issue as the author. It’s best to always start by describing the relevant context so that the reader’s brain and the writer’s brain are on the common ground before jumping into the issue. Keep in mind that there is one writer of the issue, but many readers. Here’s the best part: all the effort you put into clarity will have a huge pay off to everyone who will read it.
Tell us how to reproduce it
Another critical part of issue reporting is to provide a simple reproduction. There are two important parts to this: having a reproduction and making sure it is simple to follow You must provide the steps to reproduce an issue because, without them, the team can’t discuss anything. It is equally important that the steps are simple to follow so the issue can be reproduced. If example code is a part of the steps then it isn’t helpful to dump your existing codebase into the issue. It’s better to spend some time to whittle down the example until nothing more can be removed. The less code in reproduction the better chance that the issue can be identified quickly. Whenever possible the reproduction should be just a click away using an online editor such as https://stackblitz.com/.
A good reproduction takes the reader step by step while providing helpful context:
- Open this link
- see this text
- now click this button
- it should result in this happening but instead, this other thing happens.
Without the narrative to go with the reproduction it becomes a game of guesswork as to what the writer intended the reader to see. Assume that the reader knows nothing and walk the reader in excruciating detail step by step through the reproduction. You will not insult anyone if you include too much detail here, but excluding that detail can not only frustrate the reader but also make it harder for the team to help.
Let us know what you are thinking
Finally, the best issues are the ones that try to guess as to where in the Angular codebase the issue is. Even if the guess is completely wrong it is still helpful for the person reading the issue! Presenting a theory provides a good starting context for the reader and often leads to a faster resolution.
Conclusion
I started this post with the idea of empathy. People on both sides of the issue need to have empathy for each other. Thank you for creating issues because it only helps to make Angular better for everyone. Just remember that creating an issue is only the start. Having a clear description, great reproducible steps, and any other context you can provide makes it even more likely that your issue can be triaged and even fixed. Thanks for contributing to the Angular community!
