Introduction
GitHub Discussions is a collaborative communication forum for the community around an open source project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike GitHub Issues. Discussions enable fluid, open conversation in a public forum.
Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information.
Enabling GitHub Discussions on your repository
Repository owners and people with write access can enable GitHub Discussions for a community on their public and private repositories.
When you first enable GitHub Discussions, you will be invited to configure a welcome post.
- On GitHub.com, navigate to the main page of the repository.
- Under your repository name, click
Settings.
- Under "Features", click Set up discussions.
- Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community.
- Click Start discussion.
Welcoming contributions to your discussions
You can welcome your community and introduce a new way to communicate in a repository by creating a welcome post and pinning the post to your GitHub Discussions page. Pinning and locking discussions helps people know that a post is meant as an announcement. You can use announcements as a way to link people to more resources and offer guidance for opening discussions in your community. For more information about pinning a discussion, see "Managing discussions in your repository."
Setting up community guidelines for contributors
You can set contributing guidelines to encourage collaborators to have meaningful, useful conversations that are relevant to the repository. You can also update the repository's README to communicate expectations on when collaborators should open an issue or discussion.
For more information about providing guidelines for your project, see "Adding a code of conduct to your project" and "Setting up your project for healthy contributions."
Creating a new discussion
Any authenticated user who can view a repository can create a discussion.
- On GitHub.com, navigate to the main page of the repository.
- Under your repository name, click Discussions.
- Click New discussion.
- Select the Select Category drop-down menu, and click a category for your discussion.
- Type a title and body for your discussion.
- Click Start discussion.
Organizing discussions
Repository owners and people with write access can create new categories to keep discussions organized. Collaborators participating and creating new discussions can group discussions into the most relevant existing categories. Discussions can also be recategorized after they are created. For more information, see "Managing categories for discussions in your repository."
To organize discussions more granularly, you can apply labels. For example, you can use labels to indicate the status of a discussion to make triaging more efficient. Each repository has one shared set of labels for issues, pull requests, and discussions. For more information, see "Managing labels."
Promoting healthy conversations
People with write permissions for a repository can help surface important conversations by pinning discussions, deleting discussions that are no longer useful or are damaging to the community, and transferring discussions to more relevant repositories owned by the organization. For more information, see "Managing discussions in your repository."
People with triage permissions for a repository can help moderate a project's discussions by marking comments as answers, locking discussions that are no longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "Moderating discussions."
Next steps
Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see "Moderating discussions."