The brief subject line or title is the most important part of any issue that you write. It’s the first thing folks will see, and it gives the entire request context. Spend some time mastering this, just like you would a commit message.
The title should include verbs like "fix", "create", "give access to", etc which demonstrate the desired outcome. An action like "consider" has an ambiguous outcome, and should be avoided. Here are some examples of good and bad subject lines:
| Quality | Example | Why? |
|---|---|---|
| ❤️ | URGENT: 500 Error on product detail page | Specific, actionable |
| ❤️ | Create Web Adhoc Environment | Specific, actionable |
| 😒 | Consider strategy to block IP's | Vague, No outcome |
| 😒 | Investigate rerouting requests to different endpoint | Vague, No outcome |
| 💩 | URGENT!!! | Urgent to you? Why? What? How? |
| 💩 | Need help now!! Site is BROKEN!! | Who's Site? What's broken? |
Nothing will get your issue resolved more quickly than providing as much detail as possible the very first time you reach out with a support request. Don’t wait for folks to ask questions, give them the information up-front and you’ll get much better results.
Since we’ve moved to the latest version of Express.js, we’ve experienced a few performance issues (#14 and #15) on production.
We’ve had no way of easily seeing the performance impact before releasing our changes to production.
You can engage others (request feedback), assign somebody else to the issue, or simply leave it for further investigation, but you absolutely need to propose a next step towards solving the issue.
@bobby see with @johnny if he has a tool that could provide us insights on the performances in the development environment. We should include something similar in our development and deployment processes for future projects.
This last point is the most important, and often most disregarded, aspect of an issue thread. This is the seed of collaboration. Omitting it seriously hinders your chances of engaging others.
It is also important to try and put down all of the relevant information you can think of when creating the issue. It enables others to take over and provides invaluable context may you get to work on it days or weeks after creating it.
👍 Do "retry" whatever failed at least once more (redeploy, rerun, restart)
👍 Do add links to you references and screenshots
👍 Do Link to related issues, dependencies, etc. Any issue link,
even an issue owned by your team can help provide context.
👍 Do add a deadline/timeframe. If your issue has a deadline or timeline, provide that information.
⛔ Do not assume that just because it has a deadline that it's actually urgent.
If a certificate expires in 30 days, it's important that this ticket gets done before the deadline,
but does not require us to drop what we are doing to resolve.
👍 Do include the right people in your discussion.
Who are the most relevant people to help resolve a particular issue?
While you can assign the issue to the most suited colleague, mentioning people in the issue is
also a great way of soliciting feedback (we see a lot of /cc @bob @john in our issues).
👍 Do open one Issue for one issue.
👍 Do open two Issues for two issues.
⛔ Do not tack on “Oh by the way here’s another problem I noticed” to an unrelated Issue.
👍 Do keep facts and opinions separate, ideally facts first and opinions at the end.
Facts include platform details, reproduction steps, and what you have tried.
Opinions include speculations about root causes you have not investigated.
👍 Do be specific, especially in reproduction steps.
Instead of the instruction:
“type some text”
Be unambiguously specific with the instruction:
“Type ‘Test’”.
The bug might have to do with the shift key and it will not be reproduced by
others repeatedly banging adsfasdfadsfasd. This is not a theoretical occurrence —
underspecification remains one of the most common reasons valid issues get closed as not reproducible.
👍 Do try to consistently reproduce your issue — in a clean environment.
Start with the consistent part.
👍 Do reduce your reproduction steps to the minimal necessary to demonstrate your issue.
It makes it easier for others to help you, and the culling often reveals relevant interactions.
👍 Do specify the platform or environment, usually the browser and operating system.
This matters a lot more than one would think.
⛔ Do not include platforms that you have not tested on.
It is enough to be a legitimate bug if only one supported platform is affected.
False positives will only invite dismissal if others cannot reproduce on a platform you did not test on,
yet included in the bug report.
👍 Do report a recurring issue even without reproduction steps if you are unable to identify them,
after an earnest effort. This is sometimes okay with enough details about the environment and context,
for others to be able to help fill in the gaps.
👍 Do try to resolve or work around the issue, and provide details with what you tried,
even if it did not work.
👍 Do answer other people’s questions if you know the answer.
Responding to questions is not a privilege reserved for just maintainers.
Earnestly helping others is what open source is about!
⛔ Do not guess if you do not know the answer to someone’s question.
Signals are helpful, not noise, wherever either comes from.
👍 Do be specific in describing what you want to be added and how it would solve a problem you are facing.
⛔ Do not open an Issue with just “make X better” or “improve X”.
👍 Instead, Do open an issue for a feature request with “Make X better by adding Y because Z”.
👍 Do propose an API spec, even if it has obvious shortcomings.
This starts the conversation with concrete details, and progress can be made from there.
⛔ Do not confuse feature size with project fit. Fit is determined first, then implementation.
Some fitting features will take a long time to implement because they are large.
But no unfit features should be implemented no matter how easy.
⛔ Do not open hypothetical feature requests. If you do not personally need the feature or have the use case,
you are not qualified to recommend the solution.
👍 Do close feature requests you no longer need. If someone else has the same request,
they can open a separate issue more focused on their needs.
👍 Do search through existing issues to see if yours has already been reported.
It might even have already been resolved!
👍 Do flag other Issues as a duplicate. Sometimes it is hard to find the right search terms
in Issues and duplicates get created despite best intentions.
👍 Do keep comments short, concise and on topic. High information density is essential for
effective communication over a distributed and diverse landscape.
👍 Do read the documentation. No one wants to have to show their ugly side on a bad day.
Also known as RTFM™.
👍 Do be charitable with your interpretation of others’ words. For example, reasonable interpretations of
“What do you not understand?” include a condescending insult or hurried clarification attempt.
But the most charitable interpretation is that it is an open ended invitation to be a data point
used to improve the documentation. With global diversity of personalities and cultures participating
in open source and the low emotional density of written text, always default to the most charitable
interpretation of others’ words.
These are typically incidents & other unforeseen events. It can also include work that has a strict time-frame that if not completed would have a significant impact.
These are the activities that help you achieve your personal and professional goals, and complete important work.
Urgent but not important tasks are things that prevent you from achieving your goals.
A common source of such activities is other people. Sometimes it's appropriate to say "no" to people politely, or to encourage them to solve the problem themselves.
These activities are just a distraction – avoid them if possible.
You can simply ignore or cancel many of them. However, some may be activities that other people want you to do, even though they don't contribute to your own desired outcomes. Again, say "no" politely, if you can, and explain why you cannot do it.
- http://blog.cimcloud.com/blog/how-to-write-a-great-support-ticket
- https://hackernoon.com/45-github-issues-dos-and-donts-dfec9ab4b612
- https://wiredcraft.com/blog/how-we-write-our-github-issues/
- https://github.blog/2016-02-17-issue-and-pull-request-templates/
- https://www.mindtools.com/pages/article/newHTE_91.htm