Bug tracking & new features development by mastering GitHub Issues

by Alexander V. Ruptsov

Content List

Introduction

Each application you create on SashiDo has its own Free Private repository on GitHub.

As any great project, yours will probably need to have a way to track its bugs, tasks, and improvements. Great news, as GitHub has just the right feature for the job. Its called Issues and it’s GitHub’s way of tracking and dealing with these sort of things.

It’s really simple, as they function almost like an email, though the great part is that they can be shared and discussed with your team. Every repository comes with its own Issues section. So let's get straight to the point.

We can start by looking at Parse Server’s Issues section for example:

GitHub's tracker is also quite special. It offers excellent formatting and focuses on collaboration and references. You can check out how a typical issue on GitHub looks in the image below:

  • You can see that there is a title and a description which informs us what the issue is about.
  • There are some neat color-coded labels which help you filter and organize your issue by category.
  • Milestones are very useful for linking issues with specific feature or project phase (e.g Weekly Sprint 9/5-9/16 or Shipping 1.0). They are like a container for issues.
  • Every issue can have an assignee which is responsible for moving the issue forward.
  • And of course comments let anyone with access to the repository provide feedback and suggestions.

Milestones, Labels & Assignees

At some point, you're going to have many issues and you may find it hard to find a specific one. Don't worry, because labels, Milestones & assignees are awesome features to help you filter and sort issues.

You can change and edit all of them by just clicking on their corresponding gears in the sidebar which is located on the right.

In case you do not see the edit button, that means that you do not have permission to edit the issue and you can ask the repository's owner to make you a collaborator, so you can get access.

Milestones

Milestones are a great feature to group up your issues, for example by project, a feature or even a time period. They can be used in many different ways in software development. Here are some examples:

  • Beta Launch - You can include any bugs that need to be fixed before you release the beta. By doing so you make sure that you don't miss anything along the way.
  • June Issues - If you have many things to get done, you can specify a Milestone with the given issues you would like to work on during a specific period of time.
  • Redesign - A great way to handle issues regarding the design of your project as well as collecting new ideas along the way.

Labels

Labels are an exceptionally good way to organize your issues. There is no limit to how many labels you can have and you can even filter your issues by one or more labels at the same time.

Assignees

Each issue may have an assignee which is responsible for pushing it forward. That's a great way to assign a particular person to track the issue, and is familiar with it. That way he can easily track and push it forward.

Notifications, @mentions, and References

Communication is key to resolving any issue. By using GitHub's @mention system and references, you can link issues to the right people or teams so that the issues are resolved effectively. These features are really easy to learn and use and work in every text field as they're part of GitHub's text formatting syntax called GitHub Flavored Markdown.

If you want to learn more about the syntax, you can check GitHub's official guide on Mastering Markdown

Notifications

GitHub's way to keep you posted about your Issues is Notifications. They can be utilized so you are up-to-date with new issues or to simply know if someone's waiting for your input so they can continue with their work.

You can receive notifications by two ways - either by email or via the web. To configure these settings navigate to your notification settings.

If you plan to receive many notifications, it's suggested that you configure to receive Web & Email notifications for Participating and Web for Watching.

Given that you're using this configuration, you'll receive emails when someone specifically mentions you and you can visit the web-based interface to keep in touch with repositories you have interest in.

You can easily view your notifications in the Notifications Screen. It's located on the left of your avatar in the top-right corner of the page. There you can easily navigate through many notifications at the same time. You can mark them as read or you can mute a specific thread. You can speed up this process by using keyboard shortcuts. To check a list of available shortcuts press the ? on the page.

There is a little difference between muting a thread and marking it as read. When you've marked a certain thread as read, you will not be notified until there has been a new comment, whereas if you mute it, you will not receive notifications until you are specifically @mentioned in the thread. That gives you the power to choose which threads are important to you and which you are not interested in.

GitHub comes with an awesome feature which syncs your notification statuses. Basically, if you read a notification in your email, it will be marked as read in the web-based interface. Awesome, right. However, you should enable your email client to show images if you want this to work.

@mentions

In order to reference other GitHub users in Issues, we use the @mention system. We can do so in both the description and the comment section of an issue by including the @username of the person. When we mention someone like that they'll receive a notification about it.

If you want to include people to a given issue you can use the /cc syntax. Here's an example:

It looks like the images on our initial page are not loading.

/cc @alexSmith

That's great, but only if you know who exactly to include. In most cases, we tend to work in teams and that way we may not know who exactly could be of help. Don't worry, because @mentions work with teams within organizations on GitHub. When you @mention a team it will send notifications to everyone who's part of it. Let's say for example you create an organization named @MySashiDoApp and under it, a team @javascrip-devs. An example @mention, in this case, would look like this:

/cc @MySashiDoApp/javascript-devs

References

Quite often different issues are intertwined or maybe you just want to reference one into the other. This can be done by using the hashtag # followed by the issue number.

Hey @alexR, I think this issue may have something in common with #62

After you've done it, an event is created in issue #62 which looks something like this:

If you want to refer to an issue in an entirely different repo, just include the repository name like this alex/example_project#62

You can also reference issues directly in commits by including the issue number in the commit message.

If you preface the commit message with “Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, or “Close” and afterwards merge to master, the issue will automatically be closed.

All in all, references are great for adding visibility to the history of your project, as they profoundly link the work being done with the bug being tracked.

You can find the search box at the top of the page.

You can apply different filters to your search, for example:

If you'd like to read more about the search, you can do so in the official GitHub Article about Using search to filter issues and pull requests

Other uses for Issues

Issues are not tied only for development purposes. In fact, they are quite useful to collaborate with your team on whatever issues you have. Here are some examples:

Final

Whew! That was a long article, but you've learned how to manage and keep track of your issues.