Collaborating with maintainers using discussions

About collaboration with maintainers using GitHub Discussions

GitHub Discussions is an open forum for conversation among maintainers and the community for a repository or organization on GitHub. If you use or contribute to a project, you can start a discussion to make suggestions and engage with maintainers and community members about your plans, questions, ideas, and feedback. For more information, see "About discussions."

All discussions must be created in a category. For repository discussions, people with maintain or admin permissions to the repository define the categories for discussions in that repository. For organization discussions, people with maintain or admin permissions to the source repository define the categories for discussions in that organization. Each category has a format: open-ended discussion, question and answer, or announcement. Maintainers can use categories with the announcement format to share information, releases, or events. To keep discussions in these categories focused on important updates, only people with maintain or admin permissions can create new discussions, but anyone can comment and reply.

Repository administrators and project maintainers can delete a discussion in that repository. Similarly, administrators and maintainers of the source repository for an organization's discussions can delete a discussion in that organization. For more information, see "Managing discussions."

GitHub will automatically recognize community members who contribute the most comments marked as answers to discussions with a question/answer format. These members appear in a list of the most helpful contributors to the project's discussions, if their privacy settings allow. For more information, see "Setting your profile to private."

As your project grows, you can grant higher access permissions to active members of your community. For more information, see "Granting higher permissions to top contributors."

Community members can upvote discussions and top-level comments inside discussions to communicate with maintainers about ideas that matter to them. Project maintainers can then sort discussions and comments based on upvotes to gain insight into what community members value.

For more information about participation in discussions, see "Participating in a discussion."

Prerequisites

To collaborate with maintainers in repository discussions, a repository administrator or project maintainer must enable GitHub Discussions for the repository. For more information, see "Enabling or disabling GitHub Discussions for a repository."

To collaborate with maintainers in organization discussions, GitHub Discussions must be enabled for the organization. For more information, see "Enabling or disabling GitHub Discussions for an organization."

Starting a discussion

1. On GitHub, navigate to the main page of the repository or organization where you want to start a discussion.

2. Under your repository or organization name, click Discussions.

   

3. On the right side of the page, click New discussion.

4. Select a discussion category by clicking Get started.

   

5. Under "Discussion title", type a title for your discussion, and under "Write", type the body of your discussion.

   

6. Click Start discussion.

Starting a poll

1. On GitHub, navigate to the main page of the repository.

2. Under your repository or organization name, click Discussions.

   

3. In the list of categories, click Polls.

   

4. On the right, click New discussion.

5. Under "Discussion title", type a title and optionally, under "Write", type a body for your poll.

   

6. Under "Poll question", type a question for your poll.

7. Under "Poll options", type at least two options for your poll.

8. Optionally, to add an extra poll option, click Add an option.

   

9. Click Start poll.

Filtering the list of discussions

You can search for discussions and filter the list of discussions in a repository or organization. For more information, see "Searching discussions."

1. On GitHub, navigate to the main page of the repository or organization.

2. Under your repository or organization name, click Discussions.

   

3. In the Search all discussions field, type a search query. Optionally, to the right of the search field, click a button to further filter the results.

   

4. In the list of discussions, click the discussion you want to view.

Sorting the list of discussions

You can choose how to sort the list of discussions.

1. On GitHub, navigate to the main page of the repository or organization.

2. Under your repository or organization name, click Discussions.

   

3. To the right of the Search all discussions field, select the Sort by dropdown menu, and click a time period.

   
   • Sort by Latest activity to display the discussions with the most recent activity at the top of the list.
   • Sort by Date created to display the discussions that were created most recently at the top of the list.
   • Sort by Top to display the discussions with the most upvotes at the top of the list. You can limit the list to only display discussions from a specific time period.

Sorting top-level comments in discussions

You can choose how to sort top-level comments in discussions. Comment threads do not impact the order comments are sorted in.

1. On GitHub, navigate to the main page of the repository or organization.

2. Under your repository or organization name, click Discussions.

   

3. In the list of discussions, click the discussion you want to view.

4. Under the main discussion post, select Oldest, Newest, or Top.

   
   • Sort by Oldest to display the oldest top-level comments first.
   • Sort by Newest to display the newest top-level comments first.
   • Sort by Top to display the most upvoted top-level comments first.

Converting an issue to a discussion

If an issue turns out to be a question or open-ended conversation instead of a work item to track and prioritize, you can convert the issue to a discussion. For more information, see "Moderating discussions."

Further reading

• "About writing and formatting on GitHub"
• "Maintaining your safety on GitHub"