Skip to content
Tutorials Center
My learning

Topics

Lesson 59 of 78 ยท GitHub and Platforms

Issues, Projects and Project Management

Learn how issues, labels, milestones, templates and project boards connect to Git commits. Link commits with Fixes #12, lint messages and cut release notes.

Git tracks what changed. It does not track why you wanted the change, who asked for it, or whether it is finished. That job belongs to an issue tracker: a list of tasks, bugs and ideas that your team can discuss, label, assign and close. GitHub, GitLab, Bitbucket and Gitea all have one built in, and they all connect issues to Git in the same basic way: a number such as #12 that you can write in a commit message, a branch name or a pull request.

This lesson explains the vocabulary (issues, labels, milestones, boards), how closing keywords like Fixes #12 link commits to issues, how to write good issue templates, and how to turn commit history into release notes. The sandbox has no network and no GitHub, so everything that needs the website is shown read-only. Everything that is just text and Git (linking, linting, grouping) runs for real.

The examples use GitHub's names and syntax because it is the most common platform. GitLab, Bitbucket and others use very similar ideas with slightly different keywords.

What an issue is

An issue is a numbered discussion thread with a title, a description, a state (open or closed) and metadata: assignees, labels, a milestone and links to other issues or pull requests. Numbers are per repository and only grow: the first issue is #1, the second #2, and pull requests share the same counter on GitHub. So #12 can be an issue or a pull request, and #13 is never reused even if you delete #12.

A good issue answers four questions:

  1. What did you expect?
  2. What happened instead?
  3. How can someone reproduce it? (exact steps, versions, a minimal example)
  4. Why does it matter? (who is affected, how badly)

A bad issue says "it doesn't work". A good one lets a stranger reproduce the problem in two minutes. That is also why teams use templates, which we cover below.

Linking commits to issues

You do not need any special tool to mention an issue in Git: put #12 in the commit message and the platform makes it a clickable link. Add a closing keyword in front of it, and the platform closes the issue automatically when the commit reaches the default branch.

On GitHub the closing keywords are close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved (case-insensitive). The rule that surprises people: the keyword only closes the issue when the commit (or the pull request that contains it) is merged into the default branch. Mentioning Fixes #12 in a commit on a feature branch does nothing until it is merged.

TEXT
Add retry to the upload client

The upload stalled when the server returned 503. Retry up to three
times with exponential backoff.

Fixes #12
Refs #7

Fixes #12 closes issue 12. Refs #7 (or just #7) only creates a link. Git itself does not care: the last two lines are plain text, which is exactly why you can search for them with git log --grep.

Bash Find the commits that mention an issue

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first search finds two commits because --grep looks at the whole message, including the body: one has Fixes #12, the other only says See also #12. The second search is a regular expression for closing keywords. It matches Fixes #12 and Closes #15, but not See also #12 or refs #7. Both listed commits have a closing line. The last command pulls every #number out of every message and counts them: issue 12 appears twice, 7 and 15 once each. In a real project, that kind of query tells you how many commits touched an issue.

Write the issue number in the body or in the pull request description, not only in the subject line. Subjects are for humans scanning git log --oneline, so they should say what changed. The body can carry bookkeeping lines such as Fixes #12.

A commit-message linter you can run

Teams often want every commit (or every pull request) to reference an issue. You can enforce that with a commit-msg hook (see Git Hooks) or in CI. The logic is only a few lines of shell, so let us build it and check the history of a repository.

Bash Lint commit messages for an issue reference

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The function reads a message from standard input, so the same code works in a commit-msg hook (which gets the message in a file, so you would write lint_message < "$1") and in a loop over history, as above. Two of the four commits fail: fix stuff has no capital letter and no issue number, and the long refactor commit has a subject of 112 characters and no issue reference. The other two pass, one through (#21) in the subject and one through Fixes #22 in the body. This shows the usual compromise: a linter can check form (length, capital letter, reference) but only a reviewer can check whether the message is actually good.

Labels, assignees and milestones

Once an issue exists, three kinds of metadata keep a busy tracker usable.

Labels are short coloured tags. Most projects settle on a small set:

Label Meaning
bug Something is broken
enhancement or feature A new capability
docs Documentation only
good first issue A task suited to newcomers (see Contributing to Open Source)
help wanted Maintainers would welcome outside help
question Not a bug, a request for help
wontfix / duplicate Closed without a change

Keep the set small. Forty labels nobody remembers are worse than eight that everyone uses. Many teams also add a priority axis (p1, p2) and an area axis (area: parser, area: ui).

Assignees show who is working on an issue. Assign yourself when you start, so two people do not do the same job. On open-source projects, it is polite to comment "I'd like to work on this" and wait for a maintainer to assign it.

Milestones group issues toward a goal, usually a release or a deadline: "v2.0", "Beta 3", "Sprint 14". A milestone shows a progress bar: closed issues divided by total. It is a lightweight way to answer "are we done yet?".

Platforms keep this data on their servers, not in your repository, but you can always keep a plain-text mirror when you want to experiment. The next example computes a milestone progress report from a small exported list, exactly like a tracker would.

Bash Milestone progress from an issue list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Milestone v1.0 has two of three issues closed (66 percent, because integer division rounds down), while v2.0 has one of three. Real trackers do this for you, and they expose the same data through an API, so scripts like this one are mostly useful when you export data for a report.

Issue and pull request templates

A template is a prefilled form that appears when someone opens a new issue or pull request. Templates are plain files in your repository, so they are versioned, reviewed and branched like code. On GitHub they live in a .github folder:

TEXT
.github/
  ISSUE_TEMPLATE/
    bug_report.yml
    feature_request.yml
    config.yml
  PULL_REQUEST_TEMPLATE.md

A modern issue form is a YAML file that renders as real form fields (text boxes, dropdowns, checkboxes) with required fields. This one is read-only, because it needs GitHub to render it:

YAML
name: Bug report
description: Something is not working as documented
labels: ["bug"]
body:
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "2.4.1"
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: Exact commands or clicks, starting from a fresh install.
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options: [Windows, macOS, Linux]

The pull request template is just Markdown. It reminds authors what a reviewer needs:

TEXT
## What does this change?

## How was it tested?

## Related issues
Fixes #

## Checklist
- [ ] Tests added or updated
- [ ] Documentation updated

Because templates are only text files, you can sanity-check them in CI before a typo hides a form. The script below is a stand-in for a real YAML validator: it checks that every template has the keys GitHub requires.

Bash Sanity-check issue templates (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The feature request is missing description, so the check reports it and the script exits with status 1, which is how a CI job would turn red. A real project would use a proper YAML linter or GitHub's own schema validation, but the pattern is the same: templates are code, so test them.

Project boards

A project board shows issues as cards in columns, usually Backlog, Ready, In progress, In review and Done. GitHub Projects, GitLab Boards and Jira all offer this. A board is a different view of the same issues: moving a card changes a field on the issue, and when a linked pull request merges, many platforms move the card to Done automatically.

A few habits keep boards honest:

  • Limit work in progress. If everyone has five cards in In progress, nothing is finishing. Aim for roughly one or two per person.
  • Make cards small. An issue that takes three weeks cannot be finished or reviewed. Split it into pieces that merge in a day or two.
  • Use the board as the conversation, not a report. If a card has not moved in two weeks, ask why in the issue.
  • Keep one source of truth. Do not keep a second list in a spreadsheet.

Boards also work well with the branch workflows in Branch Workflows: one issue becomes one branch, one branch becomes one pull request, and the merge closes the issue. A simple naming convention connects them, for example feature/12-upload-retry, so anyone can see which issue a branch belongs to.

Terminal
git switch -c fix/12-upload-retry
# ...commit, push, open a pull request that says "Fixes #12"

(That snippet is read-only: it needs a remote and a platform.)

Release management

Issues and milestones lead naturally to releases. A release is a tag (see Tags and Releases) plus a description of what changed. Platforms can generate that description automatically from merged pull requests grouped by label, but you can also build it from commit messages. If your team writes messages with a type prefix (feat:, fix:, docs:, a convention called Conventional Commits), a short script groups them.

Bash Generate release notes from commits between two tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

v1.0.0..v1.1.0 means "reachable from v1.1.0 but not from v1.0.0", so the first commit is excluded. The loop prints one heading per type and skips empty groups. The numbers in brackets are issue numbers, which a platform would turn into links. For a fully worked release script, see Project: Release Automation Script.

Do not treat auto-generated notes as finished. They are a draft. Rewrite entries from the reader's point of view ("Uploads no longer stall when the server is busy") and mention breaking changes first.

Good habits at a glance

  • Search before you open an issue: duplicates waste everybody's time.
  • One issue, one problem. If a thread turns into three topics, open new issues and link them.
  • Close the loop: say what you changed in the closing commit or pull request.
  • Use Fixes #n only when the change really finishes the issue; use Refs #n for partial work.
  • Keep process in the tracker and code in Git. A decision made in a chat room is lost; a decision written in the issue survives.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. When does a commit message line Fixes #12 close issue 12 on GitHub?

    Closing keywords take effect when the commit or the pull request containing it is merged into the default branch. Mentioning an issue on a feature branch only creates a link.
  2. 2. Which command lists commits whose message mentions #12 anywhere in the subject or body?

    --grep searches commit messages. -S searches the content of the changes, and --author searches the author field.
  3. 3. What is a milestone used for?

    A milestone collects issues for a release or deadline and shows how many are closed. It is tracker metadata, not a Git object.
  4. 4. Why are issue templates stored as files in the repository?

    Templates in .github/ change through normal commits and pull requests, so improvements get reviewed and the history shows who changed them.
  5. 5. What does git log v1.0.0..v1.1.0 show?

    The two-dot range means: reachable from the right side, excluding everything reachable from the left side. It is the standard way to list what is new in a release.

Summary

  • Issues are numbered tasks and discussions; platforms store them, Git only sees the numbers you write in messages.
  • Closing keywords such as Fixes #12 close the issue when the commit reaches the default branch; Refs #12 only links.
  • git log --grep finds commits by message, so issue numbers in messages make history searchable.
  • A small shell function can lint messages for form and issue references; reviewers still judge quality.
  • Labels, assignees and milestones organize work; keep the label set small.
  • Templates in .github/ are plain files, so version and test them like code.
  • Boards are views of issues; limit work in progress and keep cards small.
  • Release notes can be drafted from the commits between two tags, then edited by a human.

Next: GitLab, Bitbucket and Self-Hosting