Issues, Projects, and Discussions

What you will learn

• Understand the core purpose of Issues, Projects, and Discussions
• Master the basic usage and common options of Issues, Projects, and Discussions
• Learn how GitHub organizes requests, work tracking, and community discussion so collaboration does not collapse into pull requests alone.
• Understand key concepts: Why PRs should not carry every conversation
• Know when to use this feature and when to avoid it

Start with a problem

You're already using GitHub or GitLab to host code, but beyond push and pull, you're not fully familiar with the collaboration features these platforms offer — PR workflows, code review, and permission management.

Why PRs should not carry every conversation

Problem Discovery

Bug reportFeature requestImprovement suggestionTask tracking

→Issue Management

Problem Solved

Labels classify priorityAssignees assign ownerMilestone links to versionProjects track progress

Good issues include: clear description, reproduction steps, expected vs actual behavior, environment info.

Teams new to GitHub often let pull requests absorb nearly all communication.
That works badly because many conversations are not really "about this diff," such as:

• feature requests
• bug tracking
• technical decisions
• iteration planning
• community questions

GitHub's issues, projects, and discussions exist to separate those collaboration modes.

Issues as work-entry points

Issues are not only for bugs. They can represent:

• defects
• feature requests
• technical debt
• tasks
• decisions that still need discussion

Thinking of an issue as a trackable work item is more useful than treating it as a simple todo entry.

What Projects adds

Projects helps teams turn many work items into an operational view:

• what is planned
• what is in progress
• what is waiting for review
• what is already done

So issues are individual units, while Projects gives you planning structure.

Why Discussions deserves its own place

Not every question should become an issue.
These often fit Discussions better:

• community questions
• exploratory ideas
• feedback threads
• user support exchanges

If everything becomes an issue, the issue queue becomes noisy and less trustworthy.

◉Issues track work, Projects organize flow, Discussions hold open conversation

These tools are strongest when they play distinct roles instead of replacing one another. That is what makes GitHub feel like a collaboration platform rather than only a code host.

A steadier collaboration model

One useful way to think about the flow is:

1. ideas, bugs, and requests start as issues
2. projects group important work into a visible planning rhythm
3. discussions handle questions and exploratory conversation
4. pull requests implement and close the loop

That keeps context cleaner than forcing every conversation into code review.

Common anti-patterns

Using PRs instead of issues

If a change has no prior context outside the PR, reviewers must reverse-engineer the problem from the diff itself.

Treating every conversation as an issue

That makes the issue list noisy and less actionable.

Creating projects but not maintaining them

A stale project board quickly becomes a surface nobody trusts.

Minimum team rules worth adding

You can start small:

1. bugs and requests begin as issues
2. PRs should link to the relevant issue when possible
3. iteration work belongs in Projects
4. open-ended questions go to Discussions first

Good follow-up reads

• feature-branch collaboration
• pull requests and reviews
• small-batch review
• merge queue workflow

Try it yourself

1. Practice the issues-projects-and-discussions command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process