Issues, labels and projects
Report bugs and plan work with issues, labels, milestones and templates, close them from pull requests, and track it all on project boards.
- Write a useful issue and organize issues with labels, assignees and milestones
- Close issues automatically from pull requests with closing keywords
- Plan work on a GitHub Projects board, and know when to use Discussions instead
An issue is a unit of work or conversation: a bug, a feature idea, a question, a chore. Dungeon Dash has a few hundred, and they’re how the team decides what to do next.
A good bug report saves everyone hours. It has:
- a specific title (“Hero clips through walls after a dash”, not “bug!!”),
- steps to reproduce,
- what you expected and what happened instead,
- versions and environment (game version, OS),
- screenshots, logs or a minimal example.
Maintainers make this easy with issue templates (files in .github/ISSUE_TEMPLATE/) that pre-fill those sections, or issue forms that turn them into a form with required fields.
Then organize:
| Tool | Use it for |
|---|---|
| Labels | type and area: bug, enhancement, docs, good first issue, area: audio |
| Assignees | who is working on it (avoids two people fixing the same bug) |
| Milestones | grouping issues for a release, like v1.5, with a progress bar |
| Issue types and sub-issues | breaking an epic into smaller pieces |
| Projects | boards and tables across issues and PRs, with custom fields like status, priority and iteration |
Not everything is an issue. Open-ended questions and ideas fit better in Discussions, a forum built into the repository - keeping the issue list for actionable work.
Closing issues from pull requests
When a pull request fixes an issue, say so with a closing keyword in its description: close, closes, closed, fix, fixes, fixed, resolve, resolves or resolved, followed by an issue reference. When the PR is merged into the default branch, GitHub closes the issue and links the two forever.
Fixes #42
Resolves dungeon-dash/level-editor#7Each issue needs its own keyword: Fixes #42, #43 closes only #42. Write Fixes #42, fixes #43. Plain mentions like “see #44” link without closing.
1import re
2
3KEYWORD = re.compile(r"\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\s+((?:[\w.-]+/[\w.-]+)?#\d+)", re.IGNORECASE)
4
5description = """Boss battle polish.
6Fixes #42, #43 and resolves #57.
7Also see #60. Closes dungeon-dash/level-editor#7"""
8print(KEYWORD.findall(description))['#42', '#57', 'dungeon-dash/level-editor#7']
Try it
Issue, discussion or pull request?
Where does each of these belong on the Dungeon Dash repository?
““The hero falls through the floor on level 3” with steps to reproduce”
““What would you all think about a multiplayer mode someday?””
“A fix for the falling-through-the-floor bug”
““How do I install the game on Linux?””
“Task: update the screenshots in the README for v1.5”
“A new level, with the level file and its test”
Key takeaways
Good issues have a clear title, reproduction steps, expected vs actual behavior and environment details.
Labels, assignees and milestones organize issues; Projects plan across them.
Closing keywords (fixes, closes, resolves...) in a PR close the issue on merge - one keyword per issue.
Use Discussions for questions and open-ended ideas, issues for actionable work.
Lesson quiz
7 questions · pass with 5 correct · up to 50 XP
Passing this quiz completes the lesson and keeps your streak going. Questions you miss come back in review sessions later.
Practice: automate GitHub chores with Python
Real GitHub work involves lots of small automation: matching CODEOWNERS, expanding build matrices, bumping versions, reading the API. Write those helpers in Python and run them against sample inputs - locally in your browser, with no GitHub account needed.
Which issues will close?
Each input line is a pull request description (on one line). Print the issues it will close when merged, as PR 1: #42, #57 (in order, without duplicates), or PR 1: none. A closing keyword - close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, in any case, optionally followed by a colon - must come directly before each reference. References are #N or owner/repo#N.
- Four PRs
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Build the triage board
Each input line is an issue as JSON: {"number": 42, "title": ..., "state": "open"|"closed", "labels": [...], "assignee": "mira"|null}. Sort them into board columns and print each column with its issues (by number) as Todo: #12 #57:
- Done: closed issues
- In progress: open issues with an assignee
- Needs triage: open, unassigned issues with no labels
- Todo: every other open issue
Print the columns in the order Needs triage, Todo, In progress, Done; print - for an empty column. Finally print good first issues: #... - open, unassigned issues labeled good first issue - or good first issues: none.
- A week of issues
- All done
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Questions about this lesson
Stuck? Ask. Figured something out? Share it. Explaining is one of the best ways to learn.
Loading posts…