How I Use GitHub Issues

I like using GitHub issues for actionable things such as bugs and backlog items I've committed to doing. Non-maintainers are encouraged open issues only for bugs, whereas everything else is a discussion.

• Bug Report 👉 Issue
• Help/support 👉 Discussion
• Ask a question 👉 Discussion
• Ideas/suggestions 👉 Discussion
• Waxing Philosophical 👉 Discussion

Alas, no matter how clear you make your templates, some folks will inevitably open issues anyway. Fear not! You can use this gem of a feature in GitHub's sidebar to convert it to a discussion. I use this very liberally. (Tip: make sure you take the time to categorize your discussions. Organization matters!)

Nobody ever got mad that their issue got turned into a discussion.

Strategic decisions #

Sometimes things that need to be addressed that aren't necessarily actionable yet. I think it's best to hash those out in discussions. RFCs, proposals, philosophical discussions are all just that…discussions.

Once a decision is made, you can create an actionable issue from the discussion summarizing the problem and the agreed solution, keeping the [often messy] details out of the issue but cleanly linking back to them for reference.

The keyword is actionable. This can be anything from "implement feature X" to "determine the best approach to Y." In the case of the latter, the issue should probably contain a follow up, e.g. "once the best approach is determined, implement and document Y".

Using this approach combined with milestones has been such a joy compared to the old way of doing issues.

Result: GitHub issues serve as a clear backlog of committed, actionable TODOs for the project. Meanwhile, the discussion forum flourishes with questions, suggestions, and other thoughts from the community.

Win-win.