Issues & Projects

Course 2 · Ch 6
Issues, Projects, and Linking PRs
Tracking bugs and tasks on GitHub itself, organising work visually, and connecting pull requests to the issues they resolve

Everything covered so far happens at the code level — commits, branches, PRs. GitHub Issues and Projects sit one layer above that: tracking what needs doing, independent of any specific branch or commit, and Projects gives that a visual board to organise around.

GitHub Issues — Tracking Work and Bugs

An issue is a tracked item — a bug report, a feature request, a task — with its own discussion thread, labels, assignees, and status. Unlike a PR, an issue doesn't require any code at all; it's pure tracking and discussion.

#42 — Login button doesn't respond on mobile Safari
bug good first issue Opened by philipo · 3 comments
Tapping the login button on iOS Safari does nothing on the first tap — works on the second tap. Doesn't reproduce on desktop Chrome or Firefox. Suspect a touch event handler issue.

What makes a useful issue

  • A clear, searchable title — "Login broken" is far less useful than "Login button doesn't respond on mobile Safari" when someone's searching for duplicates later.
  • Steps to reproduce, for bugs — what you did, what you expected, what actually happened. The single biggest factor in how quickly a bug gets fixed.
  • Labels — bug, enhancement, documentation, good first issue, and any custom labels a project defines. Makes filtering and triaging dramatically faster on any project with more than a handful of open issues.
  • Assignees — who's actually working on it, separate from who opened it.
Issues work well even on a solo project
It's tempting to think issues are only useful for teams, but tracking your own bug list and feature ideas as issues — rather than a separate notes file — keeps everything in one searchable place, linked directly to the code that eventually resolves them.

Linking Pull Requests to Issues

GitHub recognises specific keywords in a PR's description (or even a commit message) and automatically links the PR to the referenced issue — and, crucially, can close that issue automatically the moment the PR merges.

Keyword (in PR description)Effect when the PR merges
Fixes #42Automatically closes issue #42
Closes #42Same effect as "Fixes" — either works
Resolves #42Same effect — three equivalent keywords
Refs #42 / See #42Links the PR to the issue for context, but does NOT auto-close it
# In a commit message or PR description:
Fix login button touch handler on iOS Safari

Fixes #42
This works from a commit message too, not just the PR description
Putting "Fixes #42" in the commit message itself (not just the PR's own description box) means the link survives even if commits get squashed (Course 1, Chapter 7) into a single commit on merge — the keyword travels with whichever commit message contains it.

GitHub Projects — Visual Work Organisation

A Project is a customisable board (or table, or roadmap view) that organises issues and PRs visually — most commonly as columns representing stages of work, cards moving left to right as they progress.

To Do
#45 Add dark mode toggle
#46 Improve error messages
In Progress
#42 Fix login button (PR open)
Done
#40 Update README
#38 Fix typo in footer

Issues and PRs added to a Project automatically reflect their real status where GitHub can infer it — a merged PR linked to an issue can automatically move that issue's card to "Done," reducing the manual board-tidying that plagues most task-tracking tools.

When a Project is worth setting up

  • More than a handful of open issues — below that, the issues list itself is usually enough; a board adds organisational overhead without much payoff for 3-4 open items.
  • Multiple contributors needing a shared view of what's being worked on, to avoid duplicate effort.
  • Planning a release — grouping issues by milestone or target version benefits from a visual board far more than a flat list.
A Project board is not a substitute for good issue descriptions
A beautifully organised board full of vaguely-titled cards ("fix the thing", "improve stuff") is still unusable. The board organises issues; it doesn't replace the discipline of writing a clear issue in the first place.

Chapter 6 Quick Reference

  • Issues — track bugs/features/tasks with discussion, labels, and assignees; no code required
  • Good issues: clear searchable title, reproduction steps for bugs, appropriate labels, a real assignee
  • Linking keywords: Fixes/Closes/Resolves #N auto-close the issue on merge; Refs/See #N just link without closing
  • Keywords work in commit messages too — survives a squash merge, unlike text only in the PR description box
  • Projects — a visual board/table organising issues and PRs by status, useful once there's enough work to warrant it
  • A board doesn't fix bad issue descriptions — the discipline of writing clear issues still matters most
  • Next chapter: code review — practical guidance as both the author and the reviewer