Issues & Project Management

What Are GitHub Issues?

GitHub Issues are tickets for tracking work in your repository. Think of them as a to-do list, bug tracker, and discussion forum all in one.

What Issues Can Track

• Bugs: "Login button doesn't work on Safari"
• Features: "Add dark mode support"
• Tasks: "Update dependencies to latest versions"
• Questions: "How should we handle API rate limiting?"
• Documentation: "README needs installation instructions"
• Enhancements: "Improve search performance"
• Discussion: "Should we migrate to TypeScript?"

Creating Issues

Creating an Issue on GitHub

1. Go to the repository
2. Click the "Issues" tab
3. Click "New issue" button (green)
4. Fill in the form:
   • Title: Clear, concise summary
   • Description: Details about the issue
   • Assignees: Who should work on this (optional)
   • Labels: Categorize the issue
   • Projects: Add to project board (optional)
   • Milestone: Group with related issues (optional)
5. Click "Submit new issue"

Writing Effective Issue Titles

Issue Description Template

## Description
Brief overview of the issue.

## Steps to Reproduce (for bugs)
1. Go to login page
2. Click "Sign In"
3. Observe error

## Expected Behavior
What should happen?

## Actual Behavior
What actually happens?

## Environment
- Browser: Chrome 120
- OS: macOS 14
- Version: 2.1.0

## Screenshots
![Error Screenshot](url)

## Possible Solution (optional)
Ideas for how to fix this

## Additional Context
Any other relevant information

Creating Issues via GitHub CLI

# Install GitHub CLI first: https://cli.github.com

# Create issue interactively
gh issue create

# Create with inline details
gh issue create --title "Fix login bug" --body "Login fails on mobile"

# Create with labels and assignee
gh issue create --title "Add search" --label feature --assignee @me

Using Labels Effectively

Labels categorize issues, making them easy to filter and organize.

Common Label Categories

1. Type Labels

• bug - Something isn't working
• feature - New feature request
• enhancement - Improvement to existing feature
• documentation - Documentation improvements
• question - Discussion or clarification needed

2. Priority Labels

• priority: critical - Needs immediate attention
• priority: high - Important, address soon
• priority: medium - Normal priority
• priority: low - Nice to have

3. Status Labels

• in progress - Currently being worked on
• blocked - Can't proceed until something else is done
• needs review - Waiting for feedback
• ready - Ready to be worked on
• wontfix - Decided not to fix

4. Area Labels

• frontend - UI/UX related
• backend - Server/API related
• database - Database related
• deployment - CI/CD, infrastructure
• security - Security concerns

5. Contributor Labels

• good first issue - Good for newcomers
• help wanted - Looking for contributors
• beginner friendly - Easy to tackle

Creating Custom Labels

1. Go to repository → Issues tab
2. Click "Labels"
3. Click "New label"
4. Set:
   • Name: Label text
   • Description: What it means
   • Color: Visual distinction

Managing Labels via CLI

# List labels
gh label list

# Create label
gh label create "priority: high" --color "d73a4a" --description "High priority"

# Edit label
gh label edit "bug" --color "fc2929"

# Delete label
gh label delete "wontfix"

Organizing with Milestones

Milestones group related issues toward a common goal, like a release or project phase.

When to Use Milestones

• Version releases: v2.0, v2.1, v3.0
• Time-based goals: Q1 2024, Sprint 15
• Feature sets: Authentication System, API Redesign
• Events: Conference Demo, Beta Launch

Creating a Milestone

1. Go to repository → Issues tab
2. Click "Milestones"
3. Click "New milestone"
4. Fill in:
   • Title: e.g., "v2.0 Release"
   • Due date: Target completion date (optional)
   • Description: Goals and scope

Example Milestone Description

# Version 2.0 Release

Target: March 1, 2024

## Goals
- Redesigned user interface
- Performance improvements
- Dark mode support
- API v2 migration

## Success Criteria
- [ ] All critical bugs resolved
- [ ] Performance benchmarks met
- [ ] Documentation updated
- [ ] Beta testing complete

Milestone Progress Tracking

GitHub shows progress automatically:

• Open issues: Still need work
• Closed issues: Completed
• Progress bar: Visual completion percentage

Issue Workflow and Best Practices

Typical Issue Lifecycle

1. Created → Issue reported
   ↓
2. Triaged → Labels added, priority set
   ↓
3. Assigned → Someone takes ownership
   ↓
4. In Progress → Work begins
   ↓
5. PR Created → Solution proposed
   ↓
6. Reviewed → Code review
   ↓
7. Merged → Fix deployed
   ↓
8. Closed → Issue resolved

Linking Issues to Pull Requests

Connect issues to the PRs that fix them:

Automatic Closing Keywords

Use these keywords in PR descriptions or commit messages:

Fixes #123
Closes #456
Resolves #789

# When the PR merges, these issues automatically close!

# Works with multiple issues:
Fixes #123, fixes #456, closes #789

# Or in commit messages:
git commit -m "Fix login bug

Fixes #123"

Manual Linking

Reference issues without auto-closing:

Related to #123
See #456
Addresses #789

# These create links but don't auto-close

Issue Templates

Create templates to standardize issue creation:

---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - OS: [e.g. macOS]
 - Browser: [e.g. Chrome]
 - Version: [e.g. 2.0]

**Additional context**
Any other context about the problem.

---
name: Feature Request
about: Suggest an idea for this project
title: '[FEATURE] '
labels: feature
assignees: ''
---

**Is your feature request related to a problem?**
A clear description of what the problem is.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions or features you've considered.

**Additional context**
Any other context or screenshots about the feature request.

GitHub Projects (Kanban Boards)

GitHub Projects provide visual project management with Kanban boards, tables, and roadmaps.

Creating a Project

1. Go to repository → Projects tab
2. Click "New project"
3. Choose a template:
   • Board: Kanban-style columns
   • Table: Spreadsheet view
   • Roadmap: Timeline view
4. Name your project

Board View (Kanban)

Typical columns:

┌──────────┬──────────┬──────────┬──────────┐
│  Backlog │   Todo   │   Doing  │   Done   │
├──────────┼──────────┼──────────┼──────────┤
│ Issue #1 │ Issue #5 │ Issue #8 │ Issue #2 │
│ Issue #3 │ Issue #6 │ Issue #9 │ Issue #4 │
│ Issue #7 │          │          │ Issue #10│
└──────────┴──────────┴──────────┴──────────┘

Drag and drop issues between columns!

Automations

Projects can auto-update based on events:

• Auto-add: New issues → Backlog
• Auto-move: PR opened → In Progress
• Auto-close: Issue closed → Done

Custom Fields

Add metadata to issues:

• Priority: Critical, High, Medium, Low
• Size: Small, Medium, Large
• Effort: 1-5 points
• Team: Frontend, Backend, DevOps

Advanced Issue Features

Task Lists

Break issues into subtasks:

## Implementation Checklist

- [x] Design user interface
- [x] Create database schema
- [ ] Implement API endpoints
  - [x] GET /users
  - [x] POST /users
  - [ ] PUT /users/:id
  - [ ] DELETE /users/:id
- [ ] Write tests
- [ ] Update documentation

Progress: 5 of 9 tasks complete

Mentions and Notifications

# Mention users
@username can you review this?

# Mention teams
@organization/frontend-team needs to see this

# Reference other issues
This relates to #123 and #456

# Reference PRs
See PR #789 for the fix

Issue Reactions

Quick feedback without comments:

• 👍 Thumbs up - I agree
• 👎 Thumbs down - I disagree
• 😄 Laugh - Funny
• 🎉 Hooray - Excited about this
• ❤️ Heart - Love this idea
• 🚀 Rocket - Let's do it!

Saved Replies

Create template responses for common questions:

1. Settings → Saved replies
2. Create templates for:
   • "Thanks for reporting!"
   • "Need more information"
   • "Duplicate issue"
   • "Won't fix - explanation"

Issue Pinning

Pin important issues to the top:

• Important announcements
• Contributing guidelines
• Known issues
• Frequently asked questions

Searching and Filtering Issues

Basic Filters

# In the search box on Issues page:

is:open                    # Open issues only
is:closed                  # Closed issues only
is:issue                   # Issues (not PRs)
is:pr                      # Pull requests only

label:bug                  # Has 'bug' label
label:"good first issue"   # Has multi-word label
-label:bug                 # Doesn't have 'bug' label

assignee:username          # Assigned to user
assignee:@me               # Assigned to you
no:assignee                # Not assigned

milestone:"v2.0"           # In v2.0 milestone
no:milestone               # Not in any milestone

author:username            # Created by user
mentions:username          # User was mentioned

is:open is:issue assignee:@me label:bug
# Open bugs assigned to me

Advanced Search

# Search in title/body
memory leak in:title
"cannot connect" in:body

# Date filters
created:>2024-01-01        # Created after date
updated:<2024-01-01        # Updated before date
closed:2024-01-01..2024-02-01  # Closed in range

# Interaction counts
comments:>10               # More than 10 comments
comments:0                 # No comments

# Sorting
sort:created-desc          # Newest first
sort:updated-desc          # Recently updated
sort:comments-desc         # Most discussed

Saved Filters

Bookmark common searches:

• My open issues: is:open assignee:@me
• Critical bugs: is:open label:bug label:"priority: critical"
• Needs triage: is:open no:label
• Stale issues: is:open updated:<2024-01-01

Team Workflow Examples

Weekly Triage Process

1. Monday morning: Review all new issues
2. Add labels: Categorize each issue
3. Set priority: Critical, high, medium, low
4. Assign milestone: Which release?
5. Assign owner: Who should handle this?
6. Close duplicates: Reference original issue
7. Ask for more info: If details missing

Sprint Planning with Issues

1. Create milestone "Sprint 15"
2. Set due date (2 weeks)
3. Add issues to milestone
4. Sort by priority
5. Assign to team members
6. Track progress daily
7. Close completed issues
8. Move incomplete to next sprint

Release Management

1. Create milestone "v2.0 Release"
2. Add all features/bugs for v2.0
3. Track progress:
   - Dashboard shows completion %
   - Update regularly
4. Feature freeze when 80% complete
5. Only critical bugs after freeze
6. When 100% complete:
   - Create release notes
   - Tag version
   - Close milestone
   - Announce release

Practice Issue Commands (GitHub CLI)

Try these commands to manage issues from the terminal:

Issue Management Best Practices

For Maintainers

• Respond quickly: Acknowledge new issues within 24 hours
• Use templates: Ensure consistent information
• Label everything: Makes filtering easy
• Close stale issues: Keep the backlog manageable
• Be kind: Thank reporters, even for duplicates
• Link related issues: Create context
• Document decisions: Explain why issues are closed

For Contributors

• Search first: Check for duplicates
• Provide details: Steps to reproduce, environment
• One issue per issue: Don't combine multiple problems
• Be patient: Maintainers are often volunteers
• Follow up: Answer questions promptly
• Close when resolved: If you find a solution

Label System Guidelines

• Keep it simple: 10-20 labels max
• Use prefixes: priority:, type:, status:
• Document meanings: Add descriptions
• Review quarterly: Remove unused labels
• Be consistent: Always use the same labels for same things

Key Takeaways

What's Next?

Congratulations! You've completed the Collaboration Workflows section and the entire Git & GitHub tutorial series! You now have comprehensive knowledge of Git version control, GitHub collaboration, pull requests, code review, merge conflicts, and project management.

You've learned everything from basic commits to complex team workflows. You can:

• Use Git for version control locally and on GitHub
• Create branches and merge changes confidently
• Contribute to open source projects through forks and PRs
• Review code professionally and give constructive feedback
• Resolve merge conflicts without fear
• Manage projects effectively with Issues and Projects

These skills form the foundation of modern software development. Keep practicing, contribute to projects, and you'll become more proficient every day!