Communicating on GitHub

You can discuss specific projects and changes, as well as broader ideas or team goals, using different types of discussions on GitHub AE.

Introduction

GitHub AE provides built-in collaborative communication tools allowing you to interact closely with your community. This quickstart guide will show you how to pick the right tool for your needs.

You can create and participate in issues, pull requests and team discussions, depending on the type of conversation you'd like to have.

GitHub Issues

  • are useful for discussing specific details of a project such as bug reports, planned improvements and feedback.
  • are specific to a repository, and usually have a clear owner.
  • are often referred to as GitHub's bug-tracking system.

Pull requests

  • allow you to propose specific changes.
  • allow you to comment directly on proposed changes suggested by others.
  • are specific to a repository.

Team discussions

  • can be started on your team's page for conversations that span across projects and don't belong in a specific issue or pull request. Instead of opening an issue in a repository to discuss an idea, you can include the entire team by having a conversation in a team discussion.
  • allow you to hold discussions with your team about planning, analysis, design, user research and general project decision making in one place.
  • provide a collaborative experience outside the codebase, allowing the brainstorming of ideas.
  • often don’t have a clear owner.
  • often do not result in an actionable task.

Which discussion tool should I use?

Scenarios for issues

  • I want to keep track of tasks, enhancements and bugs.
  • I want to file a bug report.
  • I want to share feedback about a specific feature.
  • I want to ask a question about files in the repository.

Issue example

This example illustrates how a GitHub user created an issue in our documentation open source repository to make us aware of a bug, and discuss a fix.

Example of issue

  • A user noticed that the blue color of the banner at the top of the page in the Chinese version of the GitHub Docs makes the text in the banner unreadable.
  • The user created an issue in the repository, stating the problem and suggesting a fix (which is, use a different background color for the banner).
  • A discussion ensues, and eventually, a consensus will be reached about the fix to apply.
  • A contributor can then create a pull request with the fix.

Scenarios for pull requests

  • I want to fix a typo in a repository.
  • I want to make changes to a repository.
  • I want to make changes to fix an issue.
  • I want to comment on changes suggested by others.

Pull request example

This example illustrates how a GitHub user created a pull request in our documentation open source repository to fix a typo.

In the Conversation tab of the pull request, the author explains why they created the pull request.

Example of pull request - Conversation tab

The Files changed tab of the pull request shows the implemented fix.

Example of pull request - Files changed tab

  • This contributor notices a typo in the repository.
  • The user creates a pull request with the fix.
  • A repository maintainer reviews the pull request, comments on it, and merges it.

Scenarios for team discussions

  • I have a question that's not necessarily related to specific files in the repository.
  • I want to share news with my collaborators, or my team.
  • I want to start or participate in an open-ended conversation.
  • I want to make an announcement to my team.

Team discussion example

This example shows a team post for the octo-team team.

Example of team discussion

The octocat team member posted a team discussion, informing the team of various things:

  • A team member called Mona started remote game events.
  • There is a blog post describing how the teams use GitHub Actions to produce their docs.
  • Material about the April All Hands is now available for all team members to view.

Next steps

These examples showed you how to decide which is the best tool for your conversations on GitHub AE. But this is only the beginning; there is so much more you can do to tailor these tools to your needs.

For issues, for example, you can tag issues with labels for quicker searching and create issue templates to help contributors open meaningful issues. For more information, see "About issues" and "About issue and pull request templates."

For pull requests, you can create draft pull requests if your proposed changes are still a work in progress. Draft pull requests cannot be merged until they're marked as ready for review. For more information, see "About pull requests."

For team discussions, you can edit or delete discussions on a team's page, and you can configure notifications for team discussions. For more information, see "About team discussions."

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.