How to Write a Good GitHub Issue


"GitHub Issues" are a tracker within GitHub that essentially serves as it’s very own bug tracker. It exists in it’s own section of every repository and can be shared and discussed amongst the collaborating team. Issues are a great way to keep track of changes, enhancements, tasks, and bugs on a variety of projects, no matter the complexity. Many teams, or even open source projects, have guidelines for how to write good issues. These standards allow for streamlined communication and workflow. Impress your colleagues with well written GitHub issues by following some of these tips:


Keep Issues Separate

Document each issue separately. Simple example:

Don’t: “The form needs an email field and the submit button doesn’t function.”

Do: “Add an email field to the form.”

Do: “Submit button causes error.”


This will be important especially with more complex issues and will make them easier for your team to track and resolve.


Keep Titles Simple but Descriptive

Short, descriptive titles are easier to read, and more compelling. Often, you can save information for the issue comment to provide further clarity.



Don’t Duplicate Issues

Just like Facebook Group etiquette advises. USE THE SEARCH FEATURE before submitting an issue. If a duplicate issue is found, close the less thorough issue and link to the one remaining open.


Templates are Your Friend

Often, projects on GitHub will include issue templates. This provides guidance to contributors to submit feedback, feature requests, etc in a particular format. See how here!




Catie Carey is a freelance web developer and student in The Moms Can Code School Cohort 2. She is the Owner/Founder of Gainesville FL Moms Blog and works for the parent company, City Moms Blog Network as Technology & Resources Coordinator. She is mom to 3 boys and married to a super talented Sys Admin. She loves sunshine, fitness, food, and friends here in Gainesville Florida.



Share on Facebook
Share on Twitter
Please reload

All Content © Moms Can™ & Co.
Terms of Use & Privacy Policy