go backBack to blog

How to file better Issues on Github

Published on Apr 10 2022

Last updated on Sep 02 2022

Photo by Markus Winkler on Unsplash
No translation available.
Add translation

When working in a commercial workspace, you will have to collaborate with other members of your organization and contribute to one large repository on GitHub. There will be issues that need to be addressed while working on these projects or it could be an idea or a feature that you want to add to the repository but not sure how to do it on your own. When this happens, you will need to create a new issue under the GitHub repository but not everyone knows how to write a good GitHub issue.

How to create a new issue on GitHub

  1. Go to the repository page that you want to create an issue with.

  2. Under the repository's name, click Issues.

  3. Click the "New Issue" button and follow the templates or create a blank issue (without template).

1. Descriptive and straight-forward title

When creating your first issue, try to write a short title that contains the specific problem that you are running into. With that being said, avoid creating an issue that addresses more than one problem, you want to make a new issue request for each separate problem that you run into.

A good issue title should be less than 250 characters if possible, and address the exact problem that needed actions. Below are some examples of good and bad issue headings.

GitHub Issue Headings Examples

2. Describe the issue request effectively

Whether or not it's an issue that you run into or an idea that you'd like to implement, be descriptive and informative about it. Include all necessary information that will help other team members understand the issue easier.

  • Explain how you run into the issue, how long has it been going for, what have you done to try to resolve it and what have worked or not worked.

  • Explain the expected behavior vs. the actual behavior.

  • Including code screenshots if necessary, this is important and will help get your issue resolved faster.

  • Explain what do you want to implement.

  • Explain why you think it's a necessary feature to add.

3. Describe your approach on how to resolve the issue, or assign someone to the task

This last step is often neglected but it is one of the most important part of filing a new issue. Make sure to include:

  • Your idea on how to solve this problem, or what you think is the appropriate approach. Try to talk about it like how you would explain how to solve the problem to a colleague or an interviewer.

  • Assign this task to team members that you think are appropriate for the issue. Example is: "@sarah please take a look at this matter, discuss with @tony and let me know if you guys have any questions. If not, please proceed to solve this issue before the team meeting on .."

This section tells people that you have been working hard on solving an issue for the team, promotes collaboration and communication between team members and shows good leadership traits that are highly valued by leaders.

My portrait picture

Written by Alissa Nguyen

Alissa Nguyen is a software engineer with main focus is on building better software with latest technologies and frameworks such as Remix, React, and TailwindCSS. She is currently working on some side projects, exploring her hobbies, and living with her two kitties.

Learn more about me

If you found this article helpful.

You will love these ones as well.

  • Image by Pakata Goh on Unsplash
    Apr 21 2024 — 5 min readCoding Your First Python Web App in 5 Minutes
  • Image by Blake Connally on Unsplash
    Sep 07 2022 — 5 min readJavaScript Games to Improve your Programming Skills
  • Photo by Brendan Church on Unsplash
    Jan 22 2023 — 5 min readGitHub, GitLab, and BitBucket, Which One to Use?

  • Built and designed by Alissa Nguyen a.k.a Tam Nguyen.

    Copyright © 2024 All Rights Reserved.