How to File Useful GitHub Issues

Writing a useful GitHub Issue is important. By helping projects keep track of old bugs and plan new features, issues are part of a project's past, present, and future. However, filing a good issue takes some work.

Considerations for Filing Issues

• Search for existing issues first. Is this a duplicate? If so, go add more comments to the older issue instead.
• Provide a descriptive Title. The title will be used to quickly search through the issue list, and should describe what the issue is about
• Provide ample discussion of the issue in its Description. This should be more than a few sentences
• Does the issue relate to something visual? Include screenshots and/or video (i.e. screencast)
• If it's not visual, what is the context? For example: which OS, library version, input data, etc. are you using? Be as specific as you can, since it's not always clear what will become important.
• Is the issue a bug? Can you reproduce the bug on your machine? What are the minimal set of steps (i.e., Steps To Reproduce or STR) one needs to do in order to trigger this bug? How short can you make these steps? What's not relevant that you can ignore? Try to zero in on the actual problem. "It doesn't work" is not helpful. "It gives error 123 when I type XXX and click submit" is better.
• Is the issue a feature request? Give sufficient information for people to understand the purpose of the feature, how it will work, designs, etc.
• Does the issue reference other issues or pull requests? Include them so links are established
• Does the issue refer to existing code? Link to it.
• Have you already tried to research or debug the issue? Include the history of what you did, with links, screenshots, Markdown code blocks, etc. Build a historical reference of what has been tried.
• Has the issue been discussed on Slack, in email, etc. in the past? Copy/paste that context into the issue so that old discussions aren't lost. Be careful you don't share anything private when you do.
• Are other people involved in the issue (i.e., also experiencing it, discussed it with you)? CC them with an @ mention.
• Is this issue related to a particular area of the project that we often need to think about together? For example, is this related to the database? Consider whether we need to include an Labels so it's easier to group the related issues and find patterns, overlap, or help developers figure out what needs to be done.
• Is the issue too big? Can you break it down into smaller parts? Should it really be 3 separate issues? If fixing the issue would require a month of work, it's probably too big. Ask yourself: during that month of work, what are the sub-steps that need to get solved? File those instead.
• Is the issue Actionable? Is there a clear outcome and set of goals? What are the deliverables? For example, "Analyze component x" is too vague. You might "Analyze component x" by fixing a number of specific issues; but it's not a useful issue in and of itself.
• Prefer links to permanent URLs. If you have to include ephemeral output, embed it in the issue so it won't get lost (e.g., linking to a pastebin that expires in 2 days)

Considerations for Using Issues

• Post updates regularly on your work. Issues are living documents, and as such, you need to keep them alive by adding more context, updates, and editing information as you work on them.
• When you need to get feedback or comment from another team member, @ mention them in the issue comments. This is better than using Slack, since it leaves a historical trail. If you do discuss the issue outside of GitHub, report back into the issue with the results.
• Pull requests should reference issues by including a "Closes #..." statement in their description. This automatically closes an issue when the pull request is merged.