GitHub issues are a tool for collaboration. We can use issues to document bugs or to start discussions with our team. Every issue needs a clear title and a description of what the issue is about. Also, on the right-hand side menu, we can assign issues to people (or to ourselves), label issues, assign them as parts of projects, or milestones. We can also link issues with PRs. Issues that are linked to PRs will be closed when the PR is merged.
Here I've created an example issue. Once someone creates an issue, others con post to the conversation or share their reactions to what is being said.
If we mention an issue in a commit message, it will be shown on the issue thread.
Alternatively, if we think that the issue can be closed after we push certain changes, we can do so from the commit message. In order to do so, our commit message must include the pattern keyword #issue. The valid keywords are: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. We can close multiple issues with one commit by using commas to separate them. If we want to include a more comprehensive message we can do so with a semicolon.
git commit -m "fixes #1, closes #2, resolves #3; Commit message"
Notice that, even though this was our first issue, GitHub gave it a number two. That is because issues and PRs use the same counter. Every time we create a new issue or PR, the counter moves up by one.
I've created a new issue with the bug label. In the label tab, we can see all the default labels that all GitHub repositories come with. We can edit these labels or create new ones. On the labels tab GitHub will also show us the number of open issues or PRs that have that label.
We can assign more than one label per issue.
A related concept to that of issues is milestones. We use milestones for tasks that are composed of more than one issue. To create milestones go to the milestones tab (next to the issues tab). Milestones need a title and can optionally have a due date and a description.
Once we've created a milestone, we can also create issues and assign them to the corresponding milestone. We can also create a label that refers to this milestone.
As we work on the new milestone and close issues, GitHub will update the progress of our milestone.