Communicating on GitHub

Introduction

GitHub 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

GitHub Discussions

• Are like a forum, and are best used for open-form ideas and discussions where collaboration is important
• May span many repositories
• Provide a collaborative experience outside the codebase, allowing the brainstorming of ideas, and the creation of a community knowledge base
• 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.

Screenshot of an issue, with the title "Blue link text in notices is unreadable due to blue background."

• 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.

Screenshot of the "Conversation" tab of a pull request.

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

Screenshot of the "Files changed" tab of a pull request.

• 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 GitHub 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 community.

GitHub Discussions example

This example shows the GitHub Discussions welcome post for the GitHub Docs open source repository, and illustrates how the team wants to collaborate with their community.

Screenshot of an example of a discussion, with the title "Welcome to GitHub Docs Discussions."

This community maintainer started a discussion to welcome the community, and to ask members to introduce themselves. This post fosters an inviting atmosphere for visitors and contributors. The post also clarifies that the team's happy to help with contributions to the repository.

Using Copilot to gain context

If you need more context or clarity on a specific issue or discussion, you can use GitHub Copilot to help answer your questions. This enables you to quickly gain insights, understand complex threads, and stay aligned with the project’s goals, fostering collaboration and knowledge sharing within the community.

To ask a question about an issue or discussion:

1. From anywhere on GitHub, click the GitHub Copilot icon next to the search bar in the top right of the page.

   Screenshot of the new conversation button, highlighted with a dark orange outline.

2. In the "Ask Copilot" box, type a question and include the relevant URL in your message. For example, you could ask:

   • Explain https://github.com/monalisa/octokit/issues/1
   • Summarize https://github.com/monalisa/octokit/discussions/4
   • Recommend next steps for https://github.com/monalisa/octokit/issues/2
   • What are the acceptance criteria for ISSUE URL?
   • What are the main points made by PERSON in DISCUSSION URL?

   If you chat with GitHub Copilot from a specific issue or discussion, you don't need to include the URL in your question.

3. Optionally, after submitting a question, you can click in the text box to stop the response.

Next steps

These examples showed you how to decide which is the best tool for your conversations on GitHub. 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 GitHub Discussions, you can set up a code of conduct and pin discussions that contain important information for your community. For more information, see About discussions.

To learn some advanced formatting features that will help you communicate, see Quickstart for writing on GitHub.