Templated issue reporting in Github

A well-managed software project will inevitably have issues come up that need discussion and resolution. These might be out-and-out bugs, but more often than not they are also difficulties that people have getting started running something complex, or issues that arise when building for an environment that is not the same as what the developers have experienced.

The best projects I’ve seen have used the ability for Github to provide a template for the issue report. Rather than getting a blank page to type in your problem, you are gently guided by an already filled out page that prompts you with questions. Think of it as a simple checklist for reporting, as there are many things that someone might write, but only a few things that you really want to see.

The most useful and relevant pair of questions that I like to see are “What did you expect to see” and “What did you actually see”. Figuring out the expected future state of the system from someone else’s point of view can be a challenge, and a good prompt allows people to express what they would like to see happen even if they don’t really understand how the system really works.

Github’s mechanism for handling templated issue and pull request is written up nicely on their blog. In addition, you might like Tal Ater’s choose your own adventure decision tree to help you sort out what kind of template you might like.

The first mailbox is simply labeled issues (“as if I don’t have enough of my own to deal with”, you think to yourself).

As if!