Issues, discussions and labels

Before GitHub, reader corrections at Tidewater arrived by email, phone and handwritten notes tucked into returned books, and they were tracked in a spreadsheet that only Grace understood. At the seventh session, on January 18, Owen brought a printout of it: 63 open items, some from 2024, many duplicates, and no way to tell which had been fixed. "This is what issues are for," Priya said. The goal for the hour was to move the corrections into GitHub Issues, organize them with labels and milestones, and set up GitHub Discussions for the questions and ideas that are not really tasks.

What an issue is

An issue is a single item of work or conversation tracked in a repository: a bug report, a correction, a task, a feature request or a question. Each issue has a number, unique within the repository and shared with pull requests, so issue 31 and pull request 34 cannot have the same number. It has a title, a description written in Markdown, a comment thread, and a set of fields: assignees, labels, a milestone, project fields, and links to related pull requests and other issues. Issues are open or closed, and a closed issue can record a reason, either completed or not planned.

Anyone with read access to a repository can open an issue, which for a public repository means anyone with a GitHub account. Issues can be created from the Issues tab, from a line of code or a comment, from a project board, from GitHub Mobile, and with the gh command-line tool. Repository settings can turn issues off entirely for repositories that do not need them.

Writing a useful issue

A good issue lets someone else act on it without asking questions. For a correction, that means saying where the problem is, what is wrong, what it should say and the source. For a website bug, it means the steps to reproduce it, what you expected, what happened instead and the browser used. Owen rewrote the spreadsheet items into that pattern as he moved them, closing 14 duplicates and 9 that had already been fixed in the printed second edition.

Repositories can provide issue templates and issue forms in the .github/ISSUE_TEMPLATE folder. A template pre-fills the description with headings; a form shows structured fields, such as drop-down menus and required text boxes, so reports arrive complete. Priya made three for trail-notes: a correction form asking for the chapter, page, current text, correct text and source; a new-trail suggestion form; and a blank issue for anything else. A configuration file in the same folder can also point people elsewhere, for example to Discussions for questions.

name: Correction
description: Report an error in a guidebook
labels: ["correction"]
body:
  - type: input
    id: chapter
    attributes:
      label: Chapter and page
    validations:
      required: true
  - type: textarea
    id: correct
    attributes:
      label: What should it say, and what is your source?

Labels

Labels are coloured tags that categorize issues and pull requests. Every new repository comes with a default set: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question and wontfix. Maintainers can rename these, change their colours, delete them and add their own. Labels are most useful when there are few enough of them that everyone uses them consistently. Labels also power filters: clicking a label on the Issues tab lists every issue with it.

Two default labels matter for open source. good first issue marks tasks suitable for newcomers, and GitHub highlights repositories with such issues to people looking for a first contribution. help wanted marks issues where maintainers would welcome outside help. Malik labelled four small tasks in the public trail-report repository as good first issue the same afternoon.

Milestones and assignees

A milestone groups issues and pull requests that belong to a release or a deadline, and shows a progress bar of how many are closed. Each issue can be in one milestone. Owen created a milestone called Coastal Day Hikes 3rd edition with a due date in March 2027 and put every correction for that book in it; on the first day it showed 6 of 40 closed. An assignee is a person responsible for the issue, and an issue can have several. Assigning yourself is a simple way to tell others you have started work, so two people do not fix the same thing.

Linking issues and pull requests

Issues and pull requests are most useful when they are linked, so that an issue shows the work that fixed it and a pull request shows why it exists. There are three common ways. A closing keyword in a pull request description, such as Closes #31, links the issue and closes it when the pull request merges into the default branch; the keywords are close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved. The Development section in an issue's sidebar can link an existing pull request or branch, or create a new branch for the issue directly. And simply mentioning #31 in any comment creates a cross-reference that appears in the issue's timeline, without closing anything.

Large pieces of work can be broken down with sub-issues, child issues listed under a parent with their own progress count, and with task lists in the description. Issues can also record relationships such as blocked by another issue. Owen made the chapter 4 rewrite a parent issue with six sub-issues, one per section.

Finding issues: search and filters

The Issues tab has a search box that understands qualifiers. is:open or is:closed filters by state; label:correction filters by label; assignee:owen-tremblay or assignee:@me shows one person's work; milestone:"Coastal Day Hikes 3rd edition" shows a milestone; no:assignee finds work nobody has picked up; and words without qualifiers search titles and descriptions. Qualifiers combine, and a minus sign excludes, as in -label:duplicate. Common searches can be kept with saved views, and maintainers can store saved replies, reusable comment texts for answers they give often, such as thanking a reader and explaining when the next edition is due.

Notifications and subscriptions

You are subscribed to an issue when you open it, comment on it, are assigned to it or are mentioned in it, and you then receive notifications about new activity. You can unsubscribe from any issue, or subscribe to one you are just interested in. Repository watch settings decide what you hear about by default. Notifications can arrive in the web inbox, by email and on GitHub Mobile, and each can be configured separately in your account settings.

Keeping the issue list healthy

An issue list only helps if people trust it, so Priya showed the maintenance tools the team would use each week. Pinning keeps up to three important issues at the top of the Issues tab; the team pinned a short note explaining how to report a correction. Locking a conversation stops further comments when a thread has turned unproductive or the matter is settled, while keeping it readable. Transferring moves an issue to another repository in the same organization, with its comments, which was useful when a reader reported a website problem in trail-notes and it belonged in trailcheck. Closing an issue as not planned records that the team decided not to act, which is more honest than leaving it open forever, and marking an issue as a duplicate links it to the original so the conversation continues in one place.

Organizations can also define issue types, such as Bug, Task and Feature, that apply across all their repositories, so a report looks the same wherever it is filed. Owen set a fortnightly reminder to triage new items: read each one, apply labels and a type, add it to a milestone or close it with a reason, and assign anything urgent. By the end of January the 63-line spreadsheet had become 40 well-described issues, and nobody needed the spreadsheet again.

GitHub Discussions

Not everything is a task. Readers asked questions such as whether a trail was suitable for a dog, and volunteers suggested ideas that needed talking through before anyone decided to do them. Putting those in Issues clutters the work list. GitHub Discussions is a separate forum for a repository or organization, turned on in the settings, for conversations that are not units of work.

Discussions are organized into categories, such as Announcements, General, Ideas, Polls, Q&A and Show and tell, and maintainers can create their own. In a Q&A category, the person who asked can mark one reply as the answer, which then appears at the top. Discussions support threaded replies, reactions, polls, pinning important posts and labels. A discussion can be turned into an issue when it produces a concrete task, and an issue can be turned into a discussion when it turns out to be a question.