Skip to content

Instantly share code, notes, and snippets.

Last active May 22, 2023 16:16
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save ghostsquad/4724c90065cea42a1a9f85da3a0aebba to your computer and use it in GitHub Desktop.
Save ghostsquad/4724c90065cea42a1a9f85da3a0aebba to your computer and use it in GitHub Desktop.
Anatomy of an Effective Issue

Anatomy of an Effective Issue (or how to ask questions)

A Brief and Actionable Subject/Title

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?

Focus on the Details

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.

Context: explain the conditions which led you to write this issue

Since we’ve moved to the latest version of Express.js, we’ve experienced a few performance issues (#14 and #15) on production.

Problem or idea: the context should lead to something, an idea or a problem that you’re facing

We’ve had no way of easily seeing the performance impact before releasing our changes to production.

Solution or next step: this where you move forward

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's and Don'ts


👍 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).

Reporting Problems

👍 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.

Requesting Features

👍 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.

Being a Decent Human Being

👍 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.



Important and Urgent

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.

Important but not Urgent

These are the activities that help you achieve your personal and professional goals, and complete important work.

Not Important but Urgent

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.

Not Important and not Urgent

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.


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment