GitHub Issues
What Is an Issue?
Issues are a convenient way of identifying and delegating tasks within a single repository as well as documenting progress over time. They can also be used as a digital lab notebook for personal use to brainstorm on a novel topic or preserve important links or supplementary material for easy distribution across a whole team.
Importantly, while issues can definitely be helpful they are not required to successfully use GitHub for collaborating as a team. Issues absolutely have the potential to facilitate division of labor within a team though and are thus worth covering in this training.
An additional function that may be outside of the scope of what you need to use within your team is that it allows non-members to flag issues that they’ve had with code written by your team or request additional functionality that doesn’t yet exist in your framework. Depending on your use of packages in R you may have already opened an issue on an existing R package or workshop materials hosted in GitHub to do just that!
To see a more complete example of how issues can be used we can examine the open issues of an established R package.
Example Issue
Below is the GitHub landing page for the googldrive package and you can see that next to the underlined “Code” tab is an “Issues” tab with a gray circle with the number 22 in it. This number notifies us that as of this screen capture, there were twenty two open issues on this package’s GitHub repository.
If you click over to the issues tab you will see the titles of all current “open” (i.e., ongoing) issues on the repository. Each issue has a title and beneath that a unique number following a # as well as how long ago the issue was opened and the GitHub username of the person who opened the issue. On the right side of each issue’s thumbnail you can see the number of comments added to it.
Comments can be used to have a full dialogue among different users – potentially both in and outside of the team responsible for managing the code! The conversational aspect of issues can make them functionally similar to an email thread or messaging app chain. This communication can help keep the solutions to tasks well-documented while ensuring that every member of your group can have their voice heard.
Finding Issues in a Repository
Before we get into creating our own, it’ll be helpful to cover where issues live in GitHub. If you go to the landing page of any repository, you’ll see the–perhaps familiar–facets of the code component of GitHub: the repository’s name, the most recent commit, the files and folders in the repository, and so on.
If you look above the repository’s name you’ll see that all of this information is actually just one tab of the repository (labeled “ Code”). Note the orange underline of that tab in the screen capture below.
The next tab over is labeled “ Issue”, click that tab! You should now see the list of all issues in the repository. As we can see in the screen capture below, the most recent few issues (sorted to the top, just like commits), are focused on a cohort of LTER SPARC groups.
If we look just above the first issue we can see that 10 issues are “open” (i.e., active) and 90 are closed. By default only the open ones are displayed. Your group may not need that many issues so don’t worry too much about how many you’ve got!
What If There Aren’t Any Issues?
If you click into the ‘Issues’ tab of a repository that doesn’t have any, you’ll get a screen like the following screen capture. Note that other than the absence of issues, the screen looks the same as when there are issues (i.e., the same buttons and search/filter fields are still available).
Creating an Issue
Let’s open a new issue to demonstrate some of the useful features they provide. Click the “New issue” button to begin. This will open a dialog menu where we can begin to create our issue. Let’s start by adding a title and then clicking the “Create” button. We could do more setup stuff through this window but let’s start with the bare minimum for demonstrative purposes.
Clicking “Create” should automatically redirect you to the page for your new issue. It will automatically be given a unique (to this repository) number that you can see next to the issue’s title at the top of the screen. We’ll get to why the issue number is useful later.
There are two main categories of useful information in an issue: comments and metadata. Comments take up the majority of the horizontal area (see the wide left column) while metadata information occupies a thin column on the right side of the screen.
Metadata
When we create issues, we like to start with the metadata as this information is more useful when thinking things through from a strategic project management perspective. To clarify, the comments are also useful but they are specific to the task at hand, the metadata allow you to categorize how this issue supports the larger vision for the project.
The three facets of an issue’s metadata that you’re most likely to use are:
- Assignees
- These people will get email notifications of all activity in the issue
- Labels
- Categorical descriptors for what kind of issue this is. These can be customized and have been heavily customized in the screen captures to follow
- Type
- An interesting step one level “above” labels. The example below uses the Agile software development framework, but–like labels–you can customize these to fit your group’s needs (for more info on Agile see here)
Let’s customize those three fields for the issue we just opened. To customize any part of issue metadata click the gear icon to the right of the field you want to edit. That will open a list of possible options for that field so you can just choose the one(s) that apply to this issue. After you’ve selected some information for the issue’s metadata, your siderbar might look like the screen capture below.
Inter-Issue Relationships
While technically a facet of the metadata, it is worthwhile to make some specific time to discuss issue “relationships.” Once you have a number of issues open, it’s likely that some of them will be related! Possibly because one requires another to be completed before it can be started or maybe a number of small tasks all support a single, larger task.
Whatever the specifics, you can formally enshrine this in GitHub by editing a piece of the issue’s metadata in the right sidebar beneath most of the other issue metadata elements. The “Relationships” piece is towards the bottom of the metadata sidebar (just beneath “Milestone”).
Once you find it, click the gear icon. For synthesis working groups, “Add parent” is likely to be the most useful but if you want to add one of the other types of relationship instead, you absolutely can! Note that each issue can only have one parent, though you can change that relationship to a different issue if need be.
Regardless of the type of relationship you pick, you will now be in a dropdown menu with all the issue in this repository as options to be added as in-relationship with your current issue. You can either scroll through this list or type words that are in the title of the issue with which you want to connect your current one.
After you select one, the “Relationships” heading should clearly state which issue this one is linked with and if you click it, it will direct you to that other issue.
If you do visit the other issue, you can see all of its sub-issues in a convenient list beneath the first comment of that issue. It may look something like the following:
Working Group Use-Cases for Nesting Issues
Some use-cases of this feature for working groups include the following:
Easily find all issues related to a topic (even closed ones) by having a parent issue that is never closed–even when all of its sub-issues are closed. In this instance, your issue structure might look like the following diagram.
In the diagram below, open issues have a while closed issues have a .
Group Repository
|– Data Discovery (#1)
| |– Find Equatorial Data (#2)
| |– Identify Spatial Data Source (#3)
| L Find Trait Data (#5)
|– Quality Control (#4)
| |– Files without years (#6)
| |– Relative Abundance Data (#7)
| L Identify Spatial Data Source (#8)
L Analysis Judgement Calls (#9)
|– Distance/Dissimilarity Metric Options (#10)
|– Normalize data? (#11)
L Analyze within or across ecosystem (#12)
By leaving the parent issues open (in this example, numbers 1, 4, and 9) all of the sub-issues are easily findable if one of these judgement calls need to be revisited (whether to change track or write the relevant portion of a manuscript).
Create an issue for each manuscript section and link actionable tasks for each underneath their respective parent. In this instance, your issue structure might look like the following diagram.
In the diagram below, open issues have a while closed issues have a .
Group Repository
|– Introduction (#1)
| |– gather references (#6)
| L Outline and draft section (#8)
|– Methods (#2)
| |– Review data wrangling/analysis code (#7)
| L Outline and draft section (#9)
|– Results (#3)
| |– Settle on final figures (#10)
| L Outline and draft section (#11)
|– Discussion (#4)
| |– Review results draft (#12)
| L Outline and draft section (#14)
L Abstract (#5)
L Draft section (#13)
In this use-case, you can absolutely close parent issues after their sub-issues are all completed (see the “Methods” issue in the diagram above).
Make an issue for each sub-team then nest issues that team is responsible for as children to that parent. In this instance, your issue structure might look like the following diagram.
In the diagram below, open issues have a while closed issues have a .
Group Repository
|– Data Team (#1)
| |– Fill out Data Inventory for all datasets (#4)
| |– Data Purgatory (#7)
| L Check taxonomic names (#8)
|– Analysis Team (#2)
| |– Analyze abundance data (#5)
| |– Multivariate stats for community comp. (#6)
| L Draft figures of core story (#9)
L Writing Team (#3)
|– Outline introduction and find sources (#10)
L Draft abstract for ESA (#11)
In this use-case, you likely wouldn’t close the parent issues; or at least you wouldn’t close them until that team was finished with all of their work.
Value of Issue Numbers
Earlier in this module, we promised to get into why the unique number of each issue is useful. Simply put, you can reference issues in commits or in other issue by using their number!
When you make a commit, add a hashtag/pound sign (#) and the number of the issue that you want to reference. This will have two key results.
Most directly, the issue number in the commit message on GitHub will become a hyperlink to that issue. Anywhere the commit appears (on GitHub), the issue will be linked and easily findable.
The other feature is a little less obvious in the moment but wonderful for documenting how issues and code edits can be in conversation with one another. The commit message will show up in the comment history of the issue. So, when you are scrolling through the comments of an issue, commits that reference that issue will be visible and in chronological order with the comments. So if one comment said “can you fix this?” there could be a commit immediately below it where the commit message is “fixed per #12”.
By leveraging this feature, you can greatly simplify your commit messages because you can be confident that some of the necessary context and rationale are described in the issue and so do not need to be re-hashed in your commit message.
Referencing Issue in Other Repositories
You can even reference issues in other repositories! However, the necessary syntax does change slightly. Once you adopt that syntax though, the referenced number would have the same behavior described above when referencing issues with commits in the same repository
- Commit referencing an issue in the same repository:
fix qc code per #12 - Commit reference an issue in a different repository:
fix qc code per user/repo#12
Closing an Issue
When you’re done with an issue, simply click the “Close issue” button. It will still be findable in your repository, it just won’t show up by default when you go to the “Issues tab”. In order to see all the closed issues on a repository, simply click the Closed button in the top left of the “Issues” tab of the relevant repository.
So, even if an issue was closed in the distant past of your repository on GitHub, you can still easily access and view all of its contents! This greatly facilitates the use of issues in tracking problem solving, brainstorm sessions, and supporting documents.
Appropriate Issue Scope
As a brief aside from the nuts and bolts of how to create and manage an issue, it is important to discuss appropriate issue scope.
Essentially, an issue should directly correspond to either a single task or a single judgement call. It is not always possible to predict how projects can evolve at the outset so you may find issues spanning multiple tasks despite your best efforts but as much as you can plan to keep a 1-to-1 ratio of tasks to issues you will find delegation and tracking of task completion that much easier.
Personally, I am a longtime believer in S.M.A.R.T. goals (i.e., goals that are Specific, Measurable, Attainable, Relevant, and Time-specific), but there are many established ways of partitioning a larger project to achievable sub-tasks and you should use whichever is most intuitive to you.
If issues seem like something that your group is broadly interested in it may be worthwhile to have a conversation about some general ‘rules of thumb’ for the scope of tasks identified by issues.
Now that we’ve covered what issues are and how to open them, let’s take a minute and create some issues on your repository! On your GitHub repository, click over to the Issues tab and create a new issue. This can be either a placeholder just to have experience creating an issue or a real task that you think the team will have to deal with in the future. We are here if you need clarification!
Comments
Once you’re happy with the metadata, we can edit the first comment. “Edit” not “make” because the first comment is actually the field below the title that we left blank when we opened the issue initially. To edit that comment, click the ellipsis (…) in the top right corner of the first comment and select the “ Edit” option. Note that GitHub issues accept Markdown syntax so any tips or tricks you’ve picked up in styling the plain text of RMarkdown or Quarto files should also apply to beautifying your issue.
After you’ve edited your issue’s first comment it might look something like this.
This is the ‘back end’ of the issue displayed in the other tabset panel. Note the Markdown tricks being applied for both form and function purposes.
While issue comments are completely free for you to use as you see fit, it is important to remember that your most frequent collaborator is yourself in the future so a future version of yourself will absolutely thank you if you include as much useful context as possible. In a team setting like this one, extra detail can also really help when the person opening the issue is not the person responsible for editing the code to address it.