Issues & Projects

Code is only part of a project. Someone has to remember that the rasgulla price is wrong, that the order form needs a delivery option, and who is working on what. GitHub Issues are a to-do list built into every repository, and GitHub Projects turn those issues into planning boards and tables for the whole team.

This lesson shows how to write useful issues, organise them with labels and milestones, link them to commits and pull requests, add issue forms, and plan work in a project board.

What an issue is

An issue is a numbered discussion about one piece of work: a bug, a feature request, a question or a task. Each one has a title, a description written in Markdown, comments, and fields such as assignees and labels. Issues are numbered per repository (#1, #2, ...), and the same counter is shared with pull requests, so #14 is either an issue or a PR, never both.

Open the Issues tab and click New issue. A good bug report lets someone else reproduce the problem without asking you anything:

Title: Menu shows old price for rasgulla

What happened:
The menu page shows Rasgulla at ₹420 per kg.

What should happen:
The shop raised the price to ₹440 per kg on 1 November.

Steps to see it:
1. Open menu.html on the live site
2. Look at the third item in the list

Browser: Chrome on Android

For a feature request, describe the problem the feature solves, not only the solution: "Customers phone to ask whether we deliver to Malviya Nagar" leads to a better design than "Add a delivery checkbox".

Organising issues

New repositories come with a default set of labels, including bug, enhancement, good first issue and help wanted; you can edit them or add your own. The good first issue label is important in open source: GitHub highlights such issues to newcomers looking for somewhere to start.

Typing # followed by a number anywhere on GitHub (an issue, PR, comment or commit message) creates a link to that issue, and the linked issue shows a reference back. This builds a web of context around each piece of work.

Closing issues automatically

When a commit or pull request fixes an issue, say so with a closing keyword: close, closes, closed, fix, fixes, fixed, resolve, resolves or resolved, followed by the issue number. Priya fixes issue 14 on a branch, mentioning it in the commit body:

git commit -m "Fix rasgulla price on the menu" -m "The shop raised the price on 1 November. Fixes #14."
git log -1

[fix-rasgulla-price a002e63] Fix rasgulla price on the menu
 1 file changed, 1 insertion(+), 1 deletion(-)
commit a002e63ebc205786ffadb7eb32a773a044dbfc83
Author: Priya Sharma <priya@example.com>
Date:   Fri Oct 30 15:48:14 2026 +0530

    Fix rasgulla price on the menu

    The shop raised the price on 1 November. Fixes #14.

Each -m adds a paragraph, so the second one becomes the body. When this commit reaches the default branch (usually through a merged pull request), GitHub closes issue 14 and links it to the commit. Putting Closes #14 in the pull request description works the same way and is the most common habit. Later, anyone can find the fix from the terminal:

git log --oneline --grep="#14"

a002e63 Fix rasgulla price on the menu

Issue templates and forms

Repositories receive many issues that miss the important details. Issue forms fix this by turning "New issue" into a form with required fields. A form is a YAML file in .github/ISSUE_TEMPLATE/. Here is .github/ISSUE_TEMPLATE/bug_report.yml for the sweet-shop site:

name: Bug report
description: Something on the website is wrong or broken
title: "[Bug]: "
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: Thanks for helping us fix the Sharma Sweets website.
  - type: textarea
    id: what-happened
    attributes:
      label: What happened, and what did you expect?
      placeholder: The menu shows ₹420 for rasgulla, but the shop charges ₹440.
    validations:
      required: true
  - type: dropdown
    id: browser
    attributes:
      label: Browser
      options:
        - Chrome
        - Firefox
        - Safari
        - Edge
  - type: input
    id: page
    attributes:
      label: Page address
      placeholder: https://example.com/menu.html

Every new bug gets the bug label and a title prefix automatically, and the reporter cannot submit without describing the problem. Plain Markdown templates (.md files in the same folder) are the older, simpler alternative: they pre-fill the description but cannot enforce anything.

Planning with GitHub Projects

A project is a planning space that collects issues and pull requests, from one repository or many, and shows them in different views. Create one from your profile or organisation's Projects tab, or from a repository's Projects tab. A project has three layouts:

• Table: a spreadsheet-like list where each row is an item and each column a field.
• Board: a kanban board with columns such as Todo, In progress and Done; drag cards between columns to update their status.
• Roadmap: a timeline that places items on dates or iterations, useful for release planning.

You can add custom fields to every item: single select (priority: High, Medium, Low), number (estimate in hours), date (due date), text, and iteration (for example, two-week sprints). You can also add draft issues, quick notes that live only in the project until you convert them into real issues.

Projects also have built-in workflows that reduce manual work, such as setting an item's status to Done when its issue is closed or its pull request is merged, adding new issues from a repository automatically, and archiving old finished items. For more advanced automation, projects can be updated through GitHub Actions and the API.

Common mistakes

• Vague issues such as "site broken". Include what happened, what you expected and the steps to see it.
• One issue for many problems. Split them, so each can be assigned, discussed and closed on its own.
• Forgetting the closing keyword. Write Closes #14 in the PR description, or you will be closing issues by hand.
• Using issues as a chat room. Keep comments on topic; open a new issue for a new problem.

Key points

• Issues track bugs, features and tasks; each has a number shared with pull requests.
• Labels, assignees, milestones and task lists organise issues; good first issue welcomes newcomers.
• #14 links to issue 14; closing keywords such as Fixes #14 close it when the fix reaches the default branch.
• Issue forms in .github/ISSUE_TEMPLATE/ are YAML files that require the details you need.
• GitHub Projects show issues and PRs as a table, board or roadmap with custom fields and automatic workflows.

git switch -c fix-readme-typo
git commit -am "Fix typo in README title" -m "Closes #1."
git push -u origin fix-readme-typo