GitHub Issues

Repositories on GitHub come with several features that you can use for your development workflow. One of these features are GitHub issues. GitHub issues are a great way to plan and organize your work. You can use them to describe tasks that need to be worked on, for instance, if you store files for a paper in the repository, you could create issues for the different sections you (and your collaborators) will need to work on. If you store code in the repository, the issues could describe planned features and found bugs.

In any GitHub repository, there is a tab called “Issues”. Clicking on that tab, will bring you to the issues list. You can create a new issue by clicking the green “New issue” button on the right.

When you create a new issues, there a two fields to fill out. The title field should be a short description of the task that needs to be accomplished. Imagine a list of issues that only shows you the title. The title should convey any information necessary to understand what the issue is about. For example, “Add a new feature to allow sorting by title” is better than “sorting”. The description should contain details about the task the issue describes. The more details, the better. Especially, if you let other people using your code suggest features and report bugs, you want to define clear expectations about what information should be included in the ticket. For instance, if someone reports a bug, you most likely want to know things like the operating system they are running, what version of your code, and what parameters they have used in order to be able to reproduce the bug.

On the right side of the page, there are a few additional things you can specify such as an assignee, labels, or milestones. These can additionally help you organize your work by, for example, categorize your issues through labels or distributing work to the members of your team.