GitHub Issues and Project Boards

# CHAPTER 6

GitHub Issues and Project Boards #

1. Introduction #

Before a developer writes a single line of code, there must be a plan. If 10 developers wake up and start randomly building whatever features they feel like, the project will fail. Work must be tracked, prioritized, and assigned. While many teams use expensive external tools like Jira or Asana, GitHub provides a powerful, built-in project management ecosystem directly adjacent to your code: GitHub Issues and Project Boards. In this chapter, we will learn how to transition from chaotic ad-hoc coding to an organized, Agile development workflow utilizing Kanban boards and issue tracking.

2. Learning Objectives #

By the end of this chapter, you will be able to:

• Create and format GitHub Issues to track bugs and feature requests.

• Utilize Labels and Milestones to categorize work.

• Connect a Pull Request directly to an Issue.

• Create a GitHub Project Board (Kanban style).

• Manage Agile workflows within the GitHub ecosystem.

3. Beginner Explanation #

Imagine running a pizza restaurant.

• The Customer Order (The Issue): A customer calls and says, "I want a pepperoni pizza, hold the olives." The cashier writes this down on a sticky note. This note is the *Issue*. It describes exactly what needs to be made.

• The Order Ticket Rail (The Project Board): The cashier doesn't just hand the note to a random chef. They stick it on a metal rail above the oven. The rail has three sections: "To Do", "In Progress", and "Done".

• The Workflow: A chef grabs a ticket from "To Do", moves it to "In Progress", bakes the pizza, and then moves the ticket to "Done".

In software, Issues are the sticky notes describing the features or bugs. The Project Board is the metal rail that visually organizes the team's workload.

4. GitHub Issues #

An Issue is a formal ticket describing a piece of work. It can be a bug report ("The login button is broken on mobile") or a feature request ("Add a dark mode toggle").

Creating a Great Issue:

1. 1. Navigate to the Issues tab in your repository and click New issue.

1. 2. Title: Clear and concise (e.g., "Bug: Checkout cart crashes on Safari").

1. 3. Description: Use Markdown. Include steps to reproduce the bug, expected behavior, and actual behavior.

1. 4. Assignees: Assign it to the developer who will fix it.

1. 5. Labels: Add color-coded tags like bug, enhancement, or help wanted.

5. Connecting PRs to Issues #

The true power of GitHub is linking code to project management. If you are fixing Issue #42, you can automatically close the issue when your code is merged.

• In your Pull Request description, simply type: Fixes #42.

• GitHub will create a hyperlink. When the Head Developer clicks "Merge" on your PR, GitHub will automatically move Issue #42 to "Closed". This saves massive amounts of administrative time.

6. Mini Project: Manage Tasks with Issues #

Let's organize our workload using a Kanban board.

Step-by-Step Walkthrough:

1. 1. Navigate to your repository on GitHub.

1. 2. Go to the Projects tab and click New Project.

1. 3. Choose the Board template (this creates a Kanban layout with columns like Todo, In Progress, Done).

1. 4. Go back to the Issues tab and create three new issues:

• Issue 1: "Design Homepage layout"

• Issue 2: "Create database schema"

• Issue 3: "Write API documentation"

1. 5. Go back to your Project Board. Click the + at the bottom of the "Todo" column and add your newly created issues to the board.

1. 6. *The Simulation:* Drag "Design Homepage layout" into the "In Progress" column. You are now officially doing Agile project management!

7. Milestones #

If Labels organize *what* an issue is, Milestones organize *when* it is due. You can create a Milestone named "Version 1.0 Launch" and assign 20 issues to it. As developers close those issues, GitHub generates a progress bar, giving the Project Manager a real-time visual indicator of how close the team is to launching the product.

8. Best Practices #

• Never Code Without an Issue: A strict rule in professional teams is that no branch should exist and no code should be written unless there is an approved Issue explicitly requesting it. This prevents "Scope Creep" (developers wasting time building features the client didn't ask for).

9. Common Mistakes #

• Vague Bug Reports: Creating an issue that just says "The app is broken" is useless. A developer will spend 5 hours trying to figure out *what* is broken before they can even start fixing it. A professional bug report must include the operating system, browser version, and exact steps to reproduce the error.

10. Exercises #

1. 1. Explain the magic keyword syntax used in a Pull Request description to automatically close an associated Issue.

1. 2. Describe the visual layout and operational purpose of a Kanban board (GitHub Project Board).

11. FAQs #

Q: Can non-developers use GitHub Issues? A: Absolutely. In open-source projects, users who don't know how to code use the Issues tab constantly to report bugs or suggest features to the core developers. It acts as the project's customer support forum.

12. Summary #

In Chapter 6, we bridged the gap between project management and code execution. We learned that structured development requires formalizing tasks into GitHub Issues, ensuring every bug and feature is thoroughly documented, labeled, and assigned. We visualized our team's workflow by implementing Kanban-style Project Boards, transforming a chaotic list of tasks into an organized, trackable pipeline. By linking our Pull Requests directly to Issues using magic keywords, we automated the administrative overhead of Agile development, allowing the team to focus entirely on writing code.

13. Next Chapter Recommendation #

Our project is organized and our code is merged. But having humans manually test and deploy the code is slow and error-prone. Can we automate the robots? Proceed to Chapter 7: GitHub Actions Basics.