Which GitHub Issue to Move Forward With

Recently, I came across a GitHub issue for a feature request. The request was simple and to the point: “I want X for Y reasons.” This was helpful as it got things moving on the product development side. The challenge presented itself when we wanted to release design specifications for the request. I had many questions about the etiquette around a public issue like this.

  • Do I add my design documentation, as a comment, to the original GitHub issue that the requestor made?
  • Will people visiting the requestor’s issue read down to the comments and see my design documentation?
  • When people are searching for whether a feature has already been requested, what do they look for and expect to see?
  • Do I create a new issue and add my design documentation to it instead?
  • Do I do keep the original requestor’s issue open or close it and link to the new issue?
  • Is the requestor going to get angry that I closed their request?

After researching online, and talking to many, many designers and developers we made a decision on how we wanted to proceed.

Here is our recommendation for what to do when making a feature request in GitHub.

Acknowledge the Request

Let the person who made the feature request know, via a comment on their issue, that the team is reviewing the request. Keep the issue open for the time being.

Document the Design Specifications

This is something our team does behind the scenes, in Sketch and InVision. We design out what the feature looks like, how it functions, and additional configurations it might have.

Create a New GitHub Issue

After we (internally) review the feature’s documentation and feel confident about it, we publish a new GitHub issue. This issue has

  • A title that accurately names the feature
  • A brief description (overview) of what the feature is trying to accomplish
  • Some use cases we are trying to accomplish
  • Images to show how the feature will look and function
  • References from our research
  • Our specific labels for tracking

Comment on the New Issue

I leave a comment mentioning the original request (issue) to link the two together. This also notifies the requestor that the two issues are linked.

GitHub comment linking to the original request issue

Notify the Requestor

I also want to be considerate and make sure all parties are informed of where the feature documentation is moving to. So I let the requestor , and all those subscribed, know (via comment) that we have posted an issue documenting the request in full detail and that the original request issue will be closed. I also ask folks to review the documentation on the new issue and pick up the conversation there as well.

GitHub comment notifying everyone that the conversation has moved to a new issue

It might be redundant to add the issue number in the comment because GitHub posts a status message when I create the comment in the New Issue, but I like to be thorough. I also know that someone coming across the original issue may gloss over the GitHub messages and only read the comments. This way they can easily navigate to the new issue.

GitHub message when linking from another issue

Socialize the New Issue

We also go an extra step to notify our users who may be following our updates in other ways. We post about the new feature to our internal networks, on Slack, and on Twitter. This way, we have done our best to make sure everyone is aware that we are moving forward with a new feature, in case they were watching older requests for it.

I hope this helps others in what to do in this situation. If you have alternative ideas, please drop us a comment.

You can also follow Clarity on Twitter, star us on Github, or visit our website here.