One of the things that I like most about working with issues in the context of GitHub is that you can classify them based on what type of issue. That is, they can be be bugs, enhancements, features, or any other custom label that you opt to display them.

On top of that, GitHub-flavored markdown also makes it easy to to write well-formatted issues and comments on these issues. Over the course of this year, one of the things that I’ve found myself using more and more when filing issues has been using checkboxes to help break issues down into more incremental steps.

GitHub Issue Checkboxes

When working with issues, I used to try to breakdown each issue into it’s own ticket and then work on a set of them at one time prior to committing the changes so that each issue representing one and only one aspect of a feature or a bug, and so that a changeset reflected a batch of tickets that ultimately solved a single ticket.

This meant that a given milestone could have a seriously high-number of tickets – if a given milestone is made up of several things that need to be achieved and each of those things is made up of a number of tickets, it quickly increases in size.

But if you’re the habit of breaking down issues into the smallest units of work that go into resolving a task (which I think Git’s workflow and commit process promote this), then couldn’t a single issue also be made up of a list of smaller tasks all of which are related and that go into making up the issue?

GitHub Issue Items

Personally, I’ve found this particular approach to work well given my particular workflow. Generally speaking, it works like this:

  • Take a given task and create a single issue for it
  • In the issue, list out all of the individual steps that go into resolving it
  • Check off each list item as it’s completed
  • Once each list item has been checked off, commit the changes and close the issue
  • After each issue of a given milestone has been completed, close the milestone
  • When the milestone is closed, tag a version and release the changes to staging (or production depending on what you’re working on)

No, this doesn’t drastically vary from creating a single issue for each of the list items, but it does change, say, how quickly a given issue may be resolved.

By that, I mean there are certain tradeoffs that come with this approach: This changes discussions around an issue such that if you need to chat about an individual step for an issue, you need to be more explicit in the comments of the issue whereas if you’re creating a single issue for each item, it’s a bit easier to follow.

This also raises a point as to how much you should or shouldn’t micromanage your issues. For example, given the screenshot above, one could make a case that each heading represents a milestone and each list item represents an issue for the milestone. That works fine, too.

The thing is, I think that the amount of time that it actually takes to manage a project this way matters – if you get to where you’re micromanaging too much then you may be spending more time per milestone just checking items off and filling out information rather than getting work done.

In this approach, you’re still able to commit incremental changes and break tasks down into manageable steps, but you’re also able to spend more time focusing on checking off individual items without the overhead of managing minuté details of small issues.