Writing a proper GitHub issue
NYC Planning Labs manages almost all of its work through GitHub. So it’s important that we write well-crafted, detailed issues. Here are some best practices for writing proper GitHub issues.
Avoid duplication
The first thing you should do when writing a GitHub issue is use the search feature to make sure an issue doesn’t already exist. Of course, when working at a fast pace, duplication is bound to happen (we often create a lot of issues quickly in demos and meetings). When duplicate issues are found, one of them should be closed — typically the less thorough one. Be sure the closing comment contains a link to the issue remaining open (e.g. “Duplicate of #123”), and that any helpful details from the closed issue are consolidated into the open one.
One issue per issue
It’s also important to avoid issues that describe too much. Each bug or feature request should be documented in its own issue.
- Bad — “The form needs a subject field. Also, the submit button is broken.”
(Separate these into two issues.) - Good — “Add a subject field to form”
- Good — “Submit button causes 405 error”
It’s often unavoidable that issues are complex, especially with big feature requests. Adding a lot of detail to an issue is great! But when a complex issue can be separated into multiple issues, that makes them easier to resolve.
Titles are important
Keep your titles short and descriptive. Don’t try to cram every bit of information in the title.
For example, instead of writing the title “Search input causes error when you type over 50 characters and press enter”, use something shorter like “Search errors on 50-character submit.” The specific details — like the error happening when you press enter — can be explained in the issue comment.
More importantly, titles should also be compelling. When someone reads your issue, they should want to work on it. The title sells the issue. Don’t sacrifice allure for brevity.
Formatting
Markdown is a simple way to style your text on GitHub. A well-formatted issue is easier to read, which helps the reader to focus and understand the content. This is another way to improve the quality of your issue (and sell it to potential assignees).
- Links — Include links to the specific application views you’re describing.
- Screenshots — A picture is worth 1,000 words (a GIF is worth 1,000,000). A screenshot can help clarify the issue you’re seeing.
- @ me — If you know there are certain people that should be alerted, be sure to mention them in the issue.
Issue as user story
At Planning Labs, we’re fond of user stories. They help projects keep human-centered design at the forefront. If you can, consider including one in your issue. This is especially beneficial to feature requests.
Try following this format:
“As a [type of user] I want [my goal] so that [my reason].”
Objectivity
A good issue avoids speculation and opinion.
When describing a bug, be thorough. A little bit of investigation up front can help to clarify the issue. Open the DevTools; note any JavaScript errors and warnings; inspect the network traffic. Don’t assume you know why the bug is happening.
When requesting features and changes, clearly describe the problem to be solved instead of prescribing a solution.
- Bad — “Make the button red.”
- Good — “The user doesn’t understand that deletion is irreversible.”
Be sure to avoid hypotheticals. If you don’t need the feature or have a use case yourself, are you assuming someone does? This is another case for issue as user story.
Reproduction steps
If you’re logging a bug you’ve observed, provide instructions to reproduce the bug. Reduce the reproduction steps to their bare minimum, and try your instructions several times to make sure they reliably reproduce the same error.
Be precise in your instructions. For example, “enter text in the search input” might not be explicit enough if the error results from a specific character. Instead, “enter ‘test 123’ in the search input” includes actual text that reproduces the error.
When in doubt, follow the template
Many GitHub projects include issue templates. They’re a great way to request feedback be submitted in a particular format.
Planning Labs’ ZoLa repository includes three issue templates. When you click “New issue” on the issues page, you’re given the option to report a bug, request a feature, or open a regular issue.
Each option gives you a different template to help you write a proper issue.
🤓 Finally, be cool
We want to ensure a welcoming environment for all of our projects. Planning Labs follows the 18F Code of Conduct and all contributors should do the same.
