1. Courses
  2. Developer Foundations
  3. GitHub for Teams
  4. Stop 4

30 minBeginner

Planning on GitHub: issues, labels and Projects

GitHub can hold the plan right next to the code: issues for each piece of work, labels and fields to sort them, and Projects boards that update themselves when pull requests merge. This lesson shows how the pieces connect, and how to decide what to plan on GitHub and what to keep in Jira or Notion.

By the end you can

  • Write a bug report that a developer can act on, and a form that makes everyone write one
  • Use labels, milestones, assignees, sub-issues and issue types for what each is good at
  • Link a PR to an issue so merging closes it and moves the board
  • Set up a GitHub Project with table, board and roadmap views on the same items
  • Decide where planning lives when the team also uses Jira or Notion

The everyday picture

In the back office of a big store there is a whiteboard. Every job gets a card: "Freezer 3 not cooling", "Reprice detergent aisle for the offer", "GRN for DC delivery 4471 short by 12 cartons". Each card says who owns it and which column it is in: To do, Doing, Done. The store manager glances at it in the morning and knows what is stuck. A new staff member can read it and understand the week.

The board works only if three things are true: every job has a card, the cards are written clearly, and someone moves them. GitHub Issues are the cards, Projects is the whiteboard, and the clever part is that merging the fix moves the card for you.

An issue is a unit of work, and most of its value is in how it is written

An is a numbered card in a repository: #123. It has a title, a body written in Markdown, a comment thread, and metadata around it. Compare two bug reports for the Partner app, which independent corner shops use to order stock:

  • Vague: "App not working. Please fix urgently."
  • Useful: "Discount not applied when cart has 3+ of the same article. Partner app 2.8.0, partner shop P-1042, since this morning's update. Steps: add 3 x article 100234 (Fresh milk 1L), apply FEST10. Expected: 10% off. Actual: total unchanged, no error. Happens on 2 of 2 devices tried. Screenshot attached."

(In Mangrove's data an article is one product, and a site is one store or distribution centre; you will meet both words in real issues.) The second report can be reproduced in five minutes. The first one starts a day of phone calls. A good bug report always has the product and version, where (store or shop, device), steps, expected versus actual, impact (how many stores, is there a workaround) and evidence (screenshot, exact error text). A good feature issue states the problem and who has it before the solution, plus acceptance criteria: the checks that mean "done".

You will not get that quality by asking nicely. You get it with an : a YAML file that turns "New issue" into a form with dropdowns and required fields. The Build it section writes one.

Quick check

Which addition turns "discount broken" into a bug a developer can reproduce today?

Loading the rest of the lesson…