GitHub Issues: Basic workflow

Some advice on opening an Issue on GitHub:

  • Give it a specific title.
    • BAD: “aaaaaarrrrrrgh!”, “things not working”, “i need help”
    • GOOD: ‘error when indexing a matrix: “incorrect number of dimensions”’
  • Stay specific and be complete-but-concise in the body of the description. Don’t expect your helper to play 20 questions with you.
  • (Optional) Tag someone who really ought to see the post.
  • Don’t just create Issues – also respond to them! Think about this in terms of adding to the conversation, not in terms of “correctness”.
  • Don’t forget to click “Submit new issue”!

Typically, this will trigger an email to the person/team you tagged. The title of your issue will be in the subject line, so I repeat, make it specific. Your description will become the body of the email. At the bottom will be a link to the issue on GitHub.

If all goes well, your helper will respond. I almost always do this directly via GitHub, though simply replying to the email basically works. In any case, this back-and-forth will show up as a series of comments on your original issue. It’s like an email dialogue but better:

  • It’s embedded in a relevant Organization/project/repo, so it will be easier to find later vs. digging out of your giant vat of unfiled email.
  • It’s potentially visible to others (depending on the repo), which could save us from asking/answering the same questions repeatedly.
  • The whole discussion will be mirrored via email, so that still serves as a great way to prompt participants to tune in.
  • Later you can get fancy and refer to commits and other issues within the repo in slick ways.

Once the problem is resolved, the issue can be closed. Note that closed issues remain accessible, in case anyone needs to consult them in the future.


This piece evolved from Jenny Bryan and her past teams' work.