Collaboration · lesson 9 of 18

GitHub Issues & Projects

Track Work Like a Pro

Why it matters

Code without context is just text. Issues document what needs to be done, why, and by whom. Projects organize issues into actionable workflows.

Key concepts

Issues — Trackable units of work (bugs, features, tasks)
Labels — Categories for organizing issues
Milestones — Groups of issues targeted for a release
Projects — Kanban boards for workflow visualization

The idea

The Issue as a Contract

An issue is a contract between the reporter and the developer:

Reporter says: “Here’s what’s broken/needed, and how to reproduce it.” Developer says: “I understand and will fix/build it.”

Good issues prevent miscommunication. Bad issues waste everyone’s time.

The Lifecycle

flowchart LR
    open["Open"]
    labeled["Labeled"]
    progress["In Progress"]
    closed["Closed"]
    open -->|triage| labeled
    labeled -->|assign| progress
    progress -->|PR merged| closed

Walkthrough

Creating Effective Issues

Bug Report

## Description
Brief summary of the bug.

## Steps to Reproduce
1. Go to settings page
2. Click "Save"
3. Observe error message

## Expected Behavior
Settings should save successfully.

## Actual Behavior
Error: "Failed to save preferences"

## Environment
- OS: Ubuntu 22.04
- Browser: Firefox 120
- Version: v2.3.1

Feature Request

## Summary
What feature do you want?

## Problem
What problem does this solve?

## Proposed Solution
How should it work?

## Alternatives Considered
What other approaches did you consider?

Labels

Label	Purpose
`bug`	Something is broken
`enhancement`	New feature request
`documentation`	Docs need work
`good first issue`	Great for newcomers
`help wanted`	Extra attention needed
`priority: high`	Needs immediate attention
`wontfix`	Won’t be addressed

Milestones

Group issues by release:

v1.0 - MVP
v1.1 - Bug fixes
v2.0 - Major features

GitHub Projects (Kanban)

GitHub Projects ties issues and pull requests into a Kanban board your whole team can see.

flowchart LR
    backlog["Backlog: #45, #46, #47"]
    todo["To Do: #42, #43"]
    progress["In Progress: #40, #41"]
    done["Done: #38, #39"]
    backlog --> todo
    todo --> progress
    progress --> done

Linking PRs to Issues

# In commit message (links but doesn't close)
Refs #42

# In PR description (closes on merge)
Closes #42
Fixes #42
Resolves #42

Key takeaways

Good issues save time for everyone
Use labels to categorize and prioritize
Link PRs to issues with Closes/Refs
Projects visualize workflow status

Dos & don’ts

✅ DO

Search before creating: Maybe it’s already reported
Use templates: Consistent format helps triage
Add reproduction steps: Essential for bugs
Update status: Move cards on project boards

❌ DON’T

Don’t create vague issues: “It’s broken” is useless
Don’t create duplicate issues: Search first
Don’t mix concerns: One issue per problem
Don’t close without explanation: Say why it’s resolved

Going deeper

Issue Templates: Create .github/ISSUE_TEMPLATE/bug_report.md and feature_request.md to standardize submissions. Templates guide reporters to include necessary information.

Automation: GitHub Actions can auto-label, auto-assign, and auto-close stale issues. Projects can auto-move cards when PRs are opened/merged.

Common mistakes

Closing keywords in commits: “Closes #42” in a commit message will close the issue when ANY PR containing that commit merges. Use “Refs #42” in commits, save “Closes #42” for the PR description.

Orphaned issues: Issues without labels or milestones get lost. Triage regularly.