Issues, projects, discussions
Intermediate GitHub UI
Why this matters
Filing work well is the contribution a non-developer makes most often, and the difference between a good issue and a vague one is measured in days. GitHub also has three places to put things, and choosing wrongly buries the conversation.
Issues
Issues → New issue. A repository may offer issue templates, in which case pick the one that fits and fill in its headings rather than deleting them.
| Part | What to write |
|---|---|
| Title | The problem or outcome in one line: "Installation guide is missing the Windows steps" |
| Description | What you saw, what you expected, where. For a bug: steps, exact error text, version |
| Assignees | Leave empty unless you know; unassigned means "available" |
| Labels | Kind and area, so it can be filtered |
| Milestone | If it must ship with a particular release |
| Projects | If your team plans on a board |
Two habits again, because they matter more than the fields: paste text rather than screenshots for anything that is text, and say where by naming the file, page or URL.
Issues support task lists, and they are more than formatting: a list of - [ ] items shows as progress on the issue and on any board it appears on.
- [x] Draft the Windows steps
- [ ] Have Ben check the commands
- [ ] Update the FAQ linkIssues can also be converted into a Discussion, which is the polite way to say "this is a conversation, not a task", and can have sub-issues on the current issues experience, so a large piece of work can be broken down without a separate epic object.
Projects
A Project is a table, board and roadmap over issues and pull requests, and it lives on an organization or a user rather than inside one repository. That is its main advantage over the old repository-level boards: one project can plan work that spans five repositories.
| Concept | Means |
|---|---|
| Item | An issue, a pull request, or a draft note that has not become one yet |
| View | Table, board or roadmap, each with its own filters and grouping, saved for everyone |
| Field | A column: built-in ones like Assignee, or custom ones you define |
| Custom field | Text, number, date, single select, or iteration for sprints |
Items stay in sync with the underlying issue: changing the assignee on the board changes it on the issue, and closing the issue moves the card. A project can hold up to 50 fields, which is far more than most teams need; Status, Priority and an iteration field cover the common case.
Discussions
Discussions are forum threads attached to a repository: questions, ideas, announcements, polls. They have categories, they can be marked as answered, and they do not clutter the issue list with things nobody will ever close.
| Use | For |
|---|---|
| Issue | Something to be done, with a definition of done |
| Discussion | A question, an idea, a decision to be made, an announcement |
| Pull request | A change ready to be reviewed |
The test: if closing it would ever feel wrong, it is a Discussion.
Connecting work to Git
The issue number is the thread that ties everything together (lesson 1.6):
- In a branch name:
docs/12-windows-install-steps. - In a commit message:
docs: add Windows steps (#12)becomes a link. - In a pull request description:
Closes #12links it and closes the issue when the pull request merges.
The issue's Development section can create a branch for you, named after the issue, which is the tidiest way to start.
How to do it
Issues are GitHub's, but the number belongs in your Git:
$ git switch -c docs/12-windows-install-steps
$ git commit -m "docs: add Windows steps to installation guide (#12)"If your team uses the gh command-line tool, gh issue list and gh issue create do the rest from the same window.
The GitHub Pull Requests and Issues extension adds an Issues view, can start a branch from an issue with a configurable name, and pre-fills the commit message with the issue number.
Tools → Tasks & Contexts → Open Task… with a GitHub account configured opens an issue as a task, creates the branch and pre-fills the commit message.
The same ideas: Plan → Issues with labels and milestones, Issue boards built from labels, and epics for grouping. GitLab has no separate Discussions feature; teams use issues or the wiki. See lesson 9.6.
- Issues → New issue, choosing a template if one is offered.
- Use
#and@autocompletion in the description; add labels and a milestone. - Add it to a Project from the sidebar if your team plans there.
- In the issue's Development section, Create a branch to start work with the right name.
- Use Discussions for questions and ideas, and convert an issue to one when it turns out to be a conversation.
Common mistakes
- A title that is a category. "Bug" or "Docs" tells nobody anything.
- A screenshot of an error instead of the text.
- Using an issue for a conversation that can never be closed. Use a Discussion.
- Maintaining a board separately from the issues. Projects are a view; edit either and both change.
- Forgetting
Closes #12, so the work ships and the issue stays open.
Try it yourself
Goal: file one good issue, plan it, and start from it.
- On your practice repository, enable Issues and Discussions in Settings.
- File an issue for a real improvement: outcome as the title, location and detail in the description, a
documentationlabel. - Add a task list of three steps to the description and tick one.
- Create a Project, add the issue to it, and give it a Status field value.
- From the issue's Development section, create a branch, then check that the issue shows it.
Expected result: an issue with progress showing, a card on a board that reflects it, and a branch linked from the issue.
Show solution
Step 5 is what makes the rest worth doing. Once the branch, the commits and the pull request all carry the issue number, a person joining later can reconstruct the entire story from any one of them, which is the actual purpose of a tracker.