At GitHub, we rely on Issues heavily. Not only for bug reports, or for tracking feature implementation. We use them for almost everything. This includes, but is not limited to, discussions, announcements, ideas, tracking projects, capturing thoughts or pieces of documentation that will become pull requests, and many more.
The problem with having an abundance of issues around is you often lose track of when an issue is done. When can we close it?
Not closing issues, and losing track of what needs to be done before closing them is a pet peeve of mine.
Over the years, I developed a system to make sure I don’t let issues go stale or lose track of what needs to be done.
The system is very simple, but it works. It is based on one rule:
I need to know if I can close an issue at a glance.
The way I do it is by always including a list of actions/conditions based on the following template:
#### Actions - [ ] Some action _When everything is checked ☝️ this is considered done._
It goes in the body of an issue, at the end.
First, I start with an Actions heading. This is there to show that the following list is a list of actions. It also helps separate this section from other sections in the main issue body.
The list of actions is a task list. This means I can keep track of the progress by checking what has been completed. I can also rearrange the items without editing the issue.
An issue with a task list in its body displays the progress in various other places: repository issues list, milestones, GitHub Projects, etc.
Finally, there’s a sentence that explains the purpose of that list. When everything is checked, we can close the issue or merge the pull request. This helps everyone involved understand how I am using this list, and keeps expectations aligned.
During the life of an issue, the discussion may influence the list. I may add/change/remove items, based on how things change.
Keeping the scope small helps me manage the tasks in a better way. If the scope is big, I may need to keep an issue open for a long time. This is something I try to avoid. One way is to break a bigger task to smaller items with their own separate issue.
There are two ways to adopt a similar approach. If you own the repository, and the whole team agrees to use this system, you can create an issue template.
If it’s something you would like to do as an individual, you can create a text snippet and automate the insertion whenever you create a new issue. I am using Alfred App for that, which includes a Snippets feature. But there are dedicated applications out there like TextExpander.
This is a peek of how I work at GitHub. I hope you find it useful.