How to file better Issues on Github

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.

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.

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.

FOR AN ISSUE THAT YOU RUN INTO

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

FOR A FEATURE/IDEA

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