Issues

Last updated on 2025-02-26 | Edit this page

Estimated time: 15 minutes

Overview

Questions

  • What information should go on an Issue?
  • What are Issue templates?

Objectives

  • Create an Issue with the correct labels.
  • Assign yourself to an Issue.

GitHub Issues (tickets) are where you plan and track work. You can assign individuals to Issues and label them with a relevant tag such as bug or enhancement. Before opening a new Issue check whether there is already one open for the feature or bug by using GitHub’s search.

Here’s some advice for writing good Issues:

  • Be clear and concise, provide plenty of detail
  • State the expected outcomes
  • Tag relevant collaborators
  • Break up large Issues into several small ones and or use checklists to track tasks in the Issue

Open an Issue on the git-training-demo repository to add a file stating your favourite cloud type.

Navigate to the Issues tab:

A screenshot of the git-training-demo repository showing the Issues view.

This repositories Issue tab looks different to the weather repository you worked on in the Introduction to Git & GitHub lesson. It uses Issue templates to provide templates for bugs and feature requests. Click on the green Get started button next to the Feature request option:

A screenshot of the git-training-demo repository showing an Issue being opened. The template has automatically added text to the description and labelled the Issue as an enhancement.

You can see the Issue has text in the description already. This is from the template which provides a consistent structure to the Issues on this repo. The template has also added the enhancement label for you.

Add in a clear title such as “Add mo-fitzroy’s favourite cloud type”, replace ‘mo-fitzroy’ with your GitHub username. Click Submit new issue.

It’s a good idea to remind learners that images can be dropped straight into the Issue description. An image of a cloud should do!

Projects, milestones, and labels

Your instructor has set up a Project and some custom milestones for you to add to your Issue.

  • Labels help you classify Issues and PRs.
  • Milestones group Issues and PRs, tracking their progress towards a common milestone automatically.
  • Projects are a tool for planning and tracking work via GitHub. Multiple repositories can be linked to a single project. Projects can have multiple views depending on your needs; some have kanban boards and gantt charts, others separate out an individual colleagues Issues to avoid clutter.

Assign yourself, a project, and a milestone to your Issue

On the right hand side of the Issue you can:

  1. Assign yourself to the Issue so that others know you are working on it.
  2. Add the Issue to a Project by clicking on the cog next to the Projects section. (If you don’t see a project related to the training you might not have been granted permissions, ask your instructors for help)
  3. Assign the Issue to a milestone.

Key Points

  • Issues are used to track and plan work.
  • Issue templates provide template text for the first comment for new Issues of various types. They can auto-label Issues and encourage collaborators to give plenty of detail.