GitHub Issues and Open Source Projects
We are a full week into Hacktoberfest! The process of contributing to open source can be intimidating for new software engineers. Here is one topic to help new engineers feel more confident diving in. GitHub Issues, What are they and how do you write a good on?
What is a GitHub Issue?
GitHub Issues is a tracking system available on all GitHub repositories that can be used to report bugs and request new features. Some developer teams use GitHub issues as their bug tracking system. When looking to contribute to an open source project, the issues tab is where you can go to find what tasks need completing. (Tip! Look for good first issue label to find issues identified as appropriate for new contributors). They can be organized using labels and they keep a historical record of issues that have been closed. Issues are also a helpful and central place to discuss issues and potential fixes. They can be assigned to an individual, letting you know when someone is already working on it. Check the project’s CONTRIBUTING.md file to see how the specific project uses issues and other things to know before contributing.
You may be working in a code base and find a bug or identify a need for a new feature, first search and see if someone else has already created an issue. You want to avoid duplication and potentially add new context. Next check contribution guide for the repo to see if they have any specifics about writing a new issue. Below is a quick list of things to consider including when writing an issue.
Things to include in a GitHub Issue
Description: A clear description of the issue that provides any context needed
Screenshots: Images of any relevant UI examples of the bug or feature.
How to Reproduce (if a bug): Detailed easy-to-follow steps to reproduce. Consider adding a video if it is more complex.
Files: Link to where in the code base the issue exists. This can helps those new to the codebase navigate.
Tasks: An in-order checklist of tasks to complete in addressing the issue.
Resources: any further relevant resources that might help a contributor.
Labels: Can be used to categorize issues and indicate what skills may be needed to address an issue.
Having well-written issues can help guide other contributors to efficiently solving an issue and helps maintainers understand what you are wanting to be addressed. While comments should be used to gather more context or ask any questions, sharing this information from the beginning can save time and effort.
Want to read more? Here are some resources I found helpful in writing this blog.
