GitHub Issue for OBO Engineers
Intro to managing and tracking issues in GitHub¶
- How to create issues
- How to assign issues
- How to communicate about issues
- How to organize issues
- How to query issues
- How to close issues
- How to assign teams
- Where to go when you need help
- Miscellany that is good to know
Why: "Issues are a great way to keep track of tasks, enhancements, and bugs for your projects or for anyone else's. As long as you are a registered GitHub user you can log an issue, or comment on an issue for any open repo on GitHub. Issues are a bit like email—except they can be shared, intelligently organized, and discussed with the rest of your team. GitHub’s tracker is called Issues, and has its own section in every repository." (From: https://guides.github.com/features/issues/)
How to create an issue in GitHub:
- We will practice creating tickets in this repository https://github.com/nicolevasilevsky/c-path-practice
- Click "issues"
- Click "New Issue" (note the word 'issue' and 'ticket' are frequently used interchangeably)
- Write an informative title
- Write a detailed explanation of your issue
- In the case of reporting software bugs, provide some context in which the issue was encountered (e.g. bug detected when using Google Chrome on a Mac OS)
- If you know the sub-tasks that are involved, list these using
- [ ]markdown syntax before each bullet. Note, you can also add sub-tasks by clicking the 'add a task list' button in the tool bar. The status of the tasks in an issue (eg. https://github.com/nicolevasilevsky/c-path-practice/issues/1 will then be reflected in any summary view. Eg. https://github.com/nicolevasilevsky/c-path-practice/issues.
- Click Submit new issue
- Edit the issue (if needed) (Note that post-hoc edits will not propagate to email notifications).
Follow the instructions above to create a ticket about a hypothetical issue (such as an improvement to this tutorial) that includes a sub-task list.
Assign issues to people
- On the top right hand side, click "Assignees"
- You can assign issues to yourself or other people who are part of the repository
- In the box, start typing type their name or GitHub handle
- It is possible to assign up to 10 handles at once (assignment to a team is currently not supported)
- On the top right hand side, click "Labels"
- Assign a relevant label to your ticket
- Note, by default, every GitHub repo comes with some standard labels
- You can also create new labels that are specific to your project. For example see the labels on the Mondo GitHub tracker
- In GitHub, navigate to the Issues page or the pull requests tab
- Click Labels button next to the search field
- Click New Label to create a new label, or click Edit to edit an existing one.
- In the text box, type your new label name.
- Select a color for the label from the color bar. You can customize this color by editing the hexadecimal number above the color bar. For a list of hexadecimal numbers see HTML color codes
- Click Create Label to save the new label.
On the ticket you previously created:
- Assign the ticket to someone
- Add a label for an enhancement
- Create a new label and add it to the ticket
Communicate about issues¶
Comment on issues
- Click on an issue in the issue tracker in the https://github.com/nicolevasilevsky/c-path-practice/issues repo
- Scroll to the bottom of the issue, and add content in the "Leave a comment" field
- Use the top tool bar to format your text, add bold, italic, lists etc.
- Preview your text to see how your formatting looks
- Click Comment.
- If an issue has been addressed, click Close Issue. Best practice is to point to the work (whether code, documentation, etc) that has been done to close it.
- Only close the ticket if the issue has been resolved, usually someone will write a comment describing the action they did to close the issue and click Close Issue.
- The issue will no longer be dispalyed in the list of open issue, but will be archived.
- When making a change to code or documentation in GitHub, it is possible to automatically couple a change to an issue and close it. Just use 'fixes' or 'closes' followed by the issue number.
Use direct @ mentions
- You can mention someone in a issue without assigning it to them
- In the comments section, type @github handle. For example, to mention Nicole, you would type @nicolevasilevsky. You can either start typing their name or GitHub handle and GitHub will autosuggest their handle.
You can link documents and files by:
- copy and pasting URL
- you can attach files by dragging and dropping
- You can link one issue to another in the same repo by typing '#' followed by the title of the ticket
- This approach also works across repos but you need to use the full URL (no autocomplete available). Doing this will also cause the referent issue to display that it has been referenced.
Cross reference to another ticket
- If your ticket is a duplicate or related to another ticket, you can cross reference another ticket
- Type # and you will see a list of other tickets in that repo
- Type #TicketNumber and that will link to the other ticket.
Before saving your changes, you can preview the comment to ensure the correct formatting.
- Follow the instructions above to comment on a ticket that someone created.
- Mention Nicole
- Attach a picture (such as a picture you copy from the internet, or attach a picture you have saved on your computer)
- Include a comment that says, 'related to #1' and link to ticket #1
- To create a milestone, navigate to the issues page in your repository
- Next to the search field, click Milestones
- Click New Milestone to create a new milestone, click Edit to edit an existing one
- Create a milestone that is broad enough to be meaningful, but specific enough to be actionable.
- Set a due date for the milestone (note that specific tasks can not be formally assigned due dates, though you can mention a desired due date in the narrative text of a ticket.
- Each ticket can only be associated to ONE milestone, however it can have as many labels as appropriate.
- A given issue can be part of multiple "project" boards (see below)
Create a new milestone, and add the milestone to an existing ticket.
- Projects is a lot like Trello, it uses cards on a list that you can name and organize as you see fit.
- You can create as many projects within a repository as you like
To create project:
- Click on Projects
- Click New Project
- Name the project
- Write a description of the project
- Create columns and give them names
- Add 'cards' to the columns
Create a new project and add columns and add cards to the columns.
Once you start using GitHub for lots of things it is easy to get overwhelmed by the number of issues. The query dashboard https://github.com/issues allows you to filter on tickets.
- All issues assigned to me: https://github.com/issues/assigned
- All issues on which I am @ mentioned: https://github.com/issues/mentioned
More complex queries are also possible.
- All issues either assigned to me OR on which I have commented OR am mentioned: https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+involves%3Anicolevasilevsky+
Note, you must be signed in to GitHub to view the above links.
Further reading on Issue querys
- When you join a repository, by default, you are 'watching' all activity. You can change the setting to 'Participating and @mentions' to only get notifications that mention you
- You can set rules in your email to filter for emails that mention you, ie @username.
- You may find the answers you seek in StackOverflow, although it is primarily geared towards programmers.
- GitHub kind of monitors https://github.com/isaacs/github/issues/ but not with any rigor.
- To be safe, contact GitHub directly at https://github.com/contact, but recognize that they support literally millions of users and responsiveness is not guaranteed. Forums like isaacs sometimes offer some help because other users can help identify workarounds, for instance, as shown here.
Adopted from CD2H MTIP tutorial