Learning how to use the powerful benefits of the issue tracker
GitHub provides a fully featured issue tracker, tightly tied to each repository.
Its primary use is that of a bug tracker, since reporting and discussing bugs play a vital role in the growth of your project. It can also be used to make feature requests, serve as a discussion board of a blog or a project, and even be used as a notepad for repairing your house! For this, you can refer to the following links:
Creating a new issue
Go to https://github.com/<username>/<repository>/issues for an overview of all issue activity. If no one has ever opened an issue in your project, you will be presented with a blank page with GitHub prompting you to open a new issue. Let's go ahead and do this. Click on the big green button that says New issue.
An issue can be created when you provide the minimum of a title. Look at the following screenshot carefully where the Submit new issue button is grayed out and cannot be clicked. The title should be as descriptive as possible of the message you are trying to pass when creating an issue.
Below, under the Write tab, you can provide the details and essentially start a discussion with everyone who wants to participate (if the repository is public, that is). That's why GitHub cleverly suggests to Leave a comment.
Besides writing, you can also attach images by simply dragging and dropping, or by selecting them using folder navigation. Here's what the very first issue of this repository looks like:
Next to the Write tab is the Preview tab. In order to understand its purpose, you must first learn about Markdown.
In brief, Markdown is a text-to-HTML conversion tool so that you can write text that contains structural information and then automatically convert it to valid HTML. Written by John Gruber and adopted by GitHub (among many others), Markdown is the most well-known text-to-HTML conversion tool because of its ease of use.
Note
You can read all about how GitHub extends Markdown's functionality in the guide available at https://guides.github.com/features/mastering-markdown/.
Now, back to our new issue. As the name suggests, Preview shows what the result will be when you submit the issue. It will style the regular text of the Write tab into a meaningful text accordingly, with URLs properly formatted, images shown, emojis displayed, and so on.
Note
As we will see later in this book, GitHub-flavored Markdown has many little gems that leverage the usage of the issue tracker. What you have seen here is just the tip of the iceberg.
Feeling ready to submit it? Hit Submit new issue at the bottom of the page. Congratulations on making your first issue! The result will look as follows:
Each created issue is assigned a unique number that we can later use in other issues for reference. In our example, since this was the very first issue, it was assigned the number #1. Some useful information is provided in the title area. You can see that the issue is marked as Open, the username of the person who created it, the time it was created, and how many comments there are.
If you later realize that you made a mistake, don't panic—you can always edit the issue you created. The Edit button allows you to edit the title, and the pencil icon is used for editing the description. Close the issues using the Close issue button.
Note
You can comment and close the issue at the same time if, for example, you also want to leave a note as to why the issue got closed. Start typing a comment and the button will change from Close issue to Close and comment.
Assigning issues to users
A repository can have more than one collaborator. A collaborator is a person who has push access to the repository and, in our case, can also edit and close issues.
User assignment works well in repositories with large traffic where a team is involved and is responsible for bug fixes, enhancements, and so on.
There are two ways to assign an issue to someone. First, as you have seen in the previous images, there is an Assignee section inside each issue, as shown in the following screenshot:
At this particular stage, there is only one collaborator—me—so only my name appears in the list. Okay, we learned how to assign an issue to a collaborator from inside the issue, but what happens if you have dozens of issues that you want to assign to someone? Assigning each of them one by one is a bit tedious and time consuming. You'll be happy to know that you can mass-assign issues to a person.
For this purpose, let's create two more issues. Head over to the Issues page, select the boxes of the issues that you want to assign, and select an assignee, as shown in the following screenshot:
After selecting the assignee, the issues will immediately get updated with the new information. You can see that the avatar of the assignee appears on each issue that is assigned to them:
Note
You can select and add up to 10 assignees to an issue.
Labels
If you have worked with WordPress, labels are like tags. This is not to be confused with Git tags, though. We will now explore how to create labels and use them effectively to easily categorize batches of issues.
Why labels are a great asset to UX
Labels provide an easy way to categorize the issues based on descriptive titles, such as bug, feature, and any other words you feel like using. They are colored, and are visible throughout the issue tracker or inside each issue individually.
With labels, you can navigate to the issue tracker and filter any bloated information to visualize only the issues you are interested in. Let's see how that works.
Creating new label names and setting different colors
Head over to the issue tracker and navigate to the label page by clicking on Labels. As you can see, GitHub sets up some predefined labels that are ready to use. The name, color, and description are fully customizable for new and existing labels.
Creating a new label is as easy as pressing the New label button, filling in the name, choosing a color, and optionally entering a description. In fact, a random color is already picked, so the only prerequisite is the name. I have created a new yellow label named needs testing, as shown in the following screenshot:
After clicking the Create label button, the label will be created and appear in the list. Back to the issues—let's go inside the first one and give it the label we just created. Click on the gear icon for the dropdown to appear. Start typing to narrow down the search. Now, we only have 9 labels, but imagine having more than 42. You'd have to scroll and scroll until you found the label you were looking for.
As you might have guessed, you can choose more than one label in an issue. After you choose them, just click anywhere outside of the label window to save the action. You will see the changes immediately:
Note how GitHub makes note of any change made to the issue. This way, you will know who took a specific action and when the action was taken. Nothing escapes GitHub's eye! Try to remove the enhancement label to see what happens.
As with the assignees, you can also mass-assign labels to issues. Let's try this by going to the main issues page and selecting some issues, and then choosing the bug label:
The issue tracker will be updated, and now you can have an overview of the issues with the labels assigned to them:
Using labels to group issues
Suppose you have 100 opened issues, many labeled as bugs. Wouldn't it be cool if somehow, only those issues appeared in the Issues main page? Well guess what—when you click on the bug label, GitHub basically makes a query and, as a result, only the bug issues appear. Grouping to the rescue!
Going back to the Labels page, you can see that you can have an overview of the number of issues assigned to each label.
Milestones
Milestones, much like labels, are primarily used to group issues, but for different purposes. Consider a milestone such as a special label that has a title, a description, and an optional due date.
Why milestones are a great help when working with code versioning
It is common knowledge that applications are released in versions. From the BIOS of your laptop to the web browser you use to explore the internet, all applications use versioning.
Many companies, or even community-driven, open source projects, tend to have a road map that dictates the time when the new product will be released to the public.
GitHub integrates this feature with the issue tracker. Let's dive in and learn how to create a new milestone, attach some issues to it, and use the overview to see what issues remain resolved or unresolved.
Creating a new milestone
While at the main page of the issue tracker, click on the Milestones link, next to the Labels link. If no milestone has been created yet, you have two buttons that can create a milestone. Generally, the New milestone button will be the main one to use.
Now, let's create our first milestone. The only requirement is the title; the Description and Due Date fields are optional. However, just to see what it looks like, let's add all the information:
Hit Create milestone and it will appear in the Milestones page with all the information we previously entered:
On the left-hand side, there is the name, the due date, the description, and a note of the time the milestone was last updated. On the right-hand side, you can see the percentage of completion and the number of open and closed issues. Of course, you can edit, close, or delete it completely.
Adding issues to milestones
Now that we have at least one milestone, let's set it to an issue.
Again, there are two ways to add a milestone to an issue. Much like assignees and labels, you can do this inside each issue or mass-add it when in the Issues main page. Here, I will try the second approach; you can try the first one on your own:
After selecting the milestone, the page will be refreshed and the issue will now be added to the selected milestone. If you watch carefully, you can see a small icon and the name of the milestone next to it:
Using milestones to see which issues are resolved or are yet to be resolved
When dealing with hundreds of issues, bug reports, and enhancements, it is nice to have an overview of what is resolved and what is not.
Let's add another issue to the milestone and then immediately close it, as we learned in the Creating an issue section. In the context of the milestone, this will be considered as complete. Head over to the milestones page. You will see that the bar is now half full (at 50%):
Tips and tricks
The README files are essential for your project as they add useful information to the start page. Let's briefly explore this feature and then learn about keyboard shortcuts.
Learning about the README file
The README file is used to provide information about your project. Its content is automatically shown on the front page of your repository, so it is always a good idea to provide one file.
GitHub checks whether the README file comes with an extension; if it is supported for rendering, it automatically gets formatted according to its implementation.
For example, a README file can have a .md extension that stands for markdown, a .rst extension that stands for restructured text, and a .adoc extension that stands for AsciiDoc.
If the extension is not supported, then GitHub treats it like a regular text file and no formatting is done.
For a list of supported markups, go to https://github.com/github/markup#markups.
Navigating easily with keyboard shortcuts
GitHub has the nice feature of supporting keyboard shortcuts. You can see which shortcuts are supported by hitting ? on any page. A dialog box will pop up with all the supported shortcuts for that particular page. To see all the shortcuts, click on the Show All link.
