Skip to content

GitHub best practices for open source projects

GitHub Issues for open source

We should respond to all GitHub issues in a timely manner (generally within a few days). There are a variety of actions that can take place after reviewing a GitHub issue:

  • Convert it to a GitHub Discussion
  • Answer and close it
  • Ask for more details
  • Ask the issue creator if they would like to build the feature

It's best to link PRs to GitHub issues so the work is more trackable.

Close issues older than 6 months with a GitHub action. Let the PR author know they can re-open if it is still valid.

Assign issues to team/community members, so it’s clear who is responsible for driving the issue to completion.

Be extra kind and supportive of any community member who’s brave enough to open an issue. The issue creator should feel that our community is welcoming and supportive.

GitHub Pull Requests for open source

GitHub pull requests should have an assignee (who wrote the code), a reviewer (team member who’s reviewing the PR), and a description with “Fixes #issue_numer” that auto-closes the issue when the PR is merged.

If the comments become extensive, we should offer to help and push commits to get the PR over the finish line. In general, we don’t want to give open source contributors many rounds of comments.

GitHub Milestones for open source

GitHub issues should be assigned to milestones. The upcoming milestone should have a date. We can set the date to whatever we’d like and change it at any time.

The GitHub milestones serve as the open source roadmap. It's cumbersome to manage the roadmap with an external Google Doc or a giant issue.

Milestones offer the flexibility necessary for open source project management. When the situation changes, issues can easily be moved to different milestones.

Open source GitHub Discussions

GitHub discussions are better for Q&A, Ideas, announcements, ideas, polls, and show and tell.

It’s easy to convert GitHub issues to GitHub discussions and it’s a really nice tool when triaging issues.

GitHub discussions have features that are not available in GitHub issues, so they are an important tool for managing community interactions.