IntermediateLesson 12 of 306 min read

Issues: Tracking Work and Linking It to Commits

Turn requests into numbered issues, write good ones, and link commits so that merged work closes the right issue.

In this lesson you will

  • Write a clear issue
  • Use labels to organise issues
  • Link a commit to an issue with a closing word
  • Explain why the default branch matters

About 28 minutes

“Who is doing the rota?”

Three volunteers ask Nia the same question in one week: is anyone working on the watering rota? She could answer by message each time, but the answer would be lost. A better home for it is an issue: a numbered note on the project page that describes one piece of work, a bug, or a question. Anyone can read it, comment on it, and see whether it is open or closed. Issues turn “someone should” into “this is number 2, and Asha has it”.

What makes a good issue

  • A clear title that names the problem, such as Create a watering rota, not Help.
  • What you expected and what happened, if it is a problem.
  • The steps that show it, so another person can repeat it.
  • One topic per issue, so each can be closed on its own.

Issues also carry labels, short tags such as plan or docs, so a long list can be filtered. They can be assigned to a person and grouped into goals. Many projects add an issue template, a form that asks for the details above, which keeps new reports consistent. The exact screens and options differ by plan and change over time, so treat them as an outline and follow GitHub’s current help pages.

Linking commits to issues

The best part of issues is how they connect to Git. When a commit message or a pull request description contains a closing word followed by a hash and a number, GitHub can close that issue automatically once the work reaches the project’s default branch. The accepted words include close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved. Writing Fixes #2 is enough.

Two details matter. First, the closing only happens when the work is merged into the default branch, which is normally main. A commit sitting on a side branch does nothing yet. Second, a phrase like refs #4 is just a reference. It makes a link, but it is not a closing word.

To see this in action, here is a small history. Nia puts a closing word in one commit on main, a closing word in another commit on a side branch, and only a reference in a third.

$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ printf "Beans: row 1\n" > plan.txt
$ git add plan.txt
$ git commit -m "Add planting plan"
[main (root-commit) cd4328a] Add planting plan
 1 file changed, 1 insertion(+)
 create mode 100644 plan.txt
$ git switch -c fix-rota
Switched to a new branch 'fix-rota'
$ printf "Mon: Nia\n" > rota.txt
$ git add rota.txt
$ git commit -m "Add the rota. Fixes #2"
[fix-rota 36b68ed] Add the rota. Fixes #2
 1 file changed, 1 insertion(+)
 create mode 100644 rota.txt
$ git switch main
Switched to branch 'main'
$ echo "Carrots: row 2" >> plan.txt
$ git commit -am "Add carrots, closes #1"
[main c5ec177] Add carrots, closes #1
 1 file changed, 1 insertion(+)
$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Start on peas (refs #4)"
[main 9eff123] Start on peas (refs #4)
 1 file changed, 1 insertion(+)
$ git log --oneline --all
9eff123 Start on peas (refs #4)
c5ec177 Add carrots, closes #1
36b68ed Add the rota. Fixes #2
cd4328a Add planting plan

GitHub itself cannot be run here, so a short program plays its part. It reads the real commit messages, finds the closing words, and lists which of five made-up issues would close, first for main alone and then for every branch.

import re, subprocess
ISSUES = {
    1: ("Add carrots to the plan", "plan"),
    2: ("Create a watering rota", "rota"),
    3: ("Spell the club name correctly", "docs"),
    4: ("Plan the pea rows", "plan"),
    5: ("Choose a licence", "docs"),
}
CLOSING = r"(?i)\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)"

def closed_by(branch):
    log = subprocess.run(["git", "-C", "/home/nia/garden-notes", "log", "--format=%s", branch],
                         capture_output=True, text=True).stdout
    return sorted({int(n) for _, n in re.findall(CLOSING, log)})

for branch in ["main", "--all"]:
    print("history of", branch + ":", "closes", closed_by(branch))
print("still open after main:", sorted(set(ISSUES) - set(closed_by("main"))))
labels = {}
for number, (title, label) in ISSUES.items():
    labels.setdefault(label, []).append(number)
print("by label:", labels)
history of main: closes [1]
history of --all: closes [1, 2]
still open after main: [2, 3, 4, 5]
by label: {'plan': [1, 4], 'rota': [2], 'docs': [3, 5]}

Read the first two lines of the report. The history of main would close one issue, while the side branch holds a second. That is the rule in action: the fix for issue 2 exists, but it does not count until it is merged. Issue 4 is only referenced, so it is not in either list. Now Nia merges the side branch into main and the report is run again.

$ git merge fix-rota --no-edit
Merge made by the 'ort' strategy.
 rota.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 rota.txt
$ git log --oneline
12aa8c3 Merge branch 'fix-rota'
9eff123 Start on peas (refs #4)
c5ec177 Add carrots, closes #1
36b68ed Add the rota. Fixes #2
cd4328a Add planting plan
history of main: closes [1, 2]
history of --all: closes [1, 2]
still open after main: [3, 4, 5]
by label: {'plan': [1, 4], 'rota': [2], 'docs': [3, 5]}

After the merge, main closes issues 1 and 2, and three remain open. Everything GitHub does here is something you could build yourself from commit messages, which is why writing messages carefully pays off.

Habits that keep issues useful

  • Search the existing issues before opening a new one, so you do not create duplicates.
  • Close an issue by merging work, not by leaving a comment that says it is done.
  • Say what you are working on, so two people do not fix the same thing.
  • Be kind in comments. A project is a group of people, and the tone you set is part of it.
Common mistake: expecting an instant close

Writing fixes #2 in a commit on a side branch and expecting the issue to close at once. It closes only when that work reaches the default branch.

A sketch of the rule, not the website

The issue list and labels are made up, and the program only imitates the closing rule so you can see it work. The exact keywords, features and screens on GitHub can change, so confirm them in its current help pages.

Write three issues for a project of your own, each with a clear title, one steps list and one label. Then write the commit message that would close the first one.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What is an issue?

  1. A kind of branch
  2. A numbered note describing one piece of work, a bug or a question
  3. A password
  4. A commit ID

Issues give work a name and a number that everyone can see.

Which commit phrase can close issue 2?

  1. See issue 2
  2. Issue two maybe
  3. Fixes #2
  4. Refs #2

A closing word followed by the number does it, while refs only links.

When does a closing word actually close the issue?

  1. When the work is merged into the default branch
  2. The moment you commit it on any branch
  3. After a week
  4. Never automatically

The side branch fix did not count until the merge.

Why was issue 4 not in the closing list?

  1. It had no number
  2. It was on GitHub
  3. Its commit said refs, which is a reference and not a closing word
  4. It was too long

Start on peas (refs #4) makes a link only.

What is a label for?

  1. Filtering and grouping issues, such as plan or docs
  2. Encrypting an issue
  3. Naming a commit
  4. Deleting a branch

The report grouped the issues by label.

Summary

  • An issue is a numbered note about one piece of work.
  • Closing words such as fixes or closes plus a number can close an issue.
  • Closing happens when the work reaches the default branch, not before.
  • Refs only creates a link; labels help you filter.

Next lesson

Lesson 13 turns a branch into a pull request and compares the three ways to merge it.

Questions

Do I have to use closing words?

No. You can close an issue by hand. Closing words are a convenience that keeps work and its record connected.

Can one commit close several issues?

Yes, but each issue number needs its own closing word, for example fixes #1 and fixes #2.

What if the issue is in a different repository?

GitHub supports a longer form that names the owner and the repository before the number. Check its current help page for the exact syntax.

Progress is saved in this browser.