Disclaimer: This is a personal perspective. The majority of OSS projects I contribute to are libraries and developer tooling. The side effect of this is that if a person is using one of these projects, they have the expertise to understand and modify the code of the project. Also many of the comments made are from my experience, your experience may vary.
GitHub Issues are used for many different types of interactions.
- Bug tracking
- Q/A
- Forum style conversations
- Chat style interactions
However, issues cannot be the best approach for all these interactions. This is why the majority of projects push people to other mechanisms for various subsets. eg Q/A to StackOverflow, or chat to Gitter.
There is a common belief/perception amongst many users of OSS that (to get a bug fixed, a feature added, or a question answered) all that is required is to create an issue. There are several problems with this
- A bug may require significant work to even get to the state that it is confirmed as a bug.
- A feature can require significant work to spec out, implement, and support. It also might not have enough value for the majority of users.
- A question might require significant interactions to even understand, let alone be able to answer.
Unfortunately, the expectation from many is that someone should eventually resolve it by (fixed, added, or answered), and if not it should remain open forever. If an issue is closed (due to not enough info, no answer, not viable feature, etc) that social contract is broken and feelings are hurt.
Many projects attempt to mitigate the above by having Issue templates. An issue template can
- define "the rules of engagement" for a project
- set the expectations for the various parties involved
- guide people to better approaches for various scenarios
In my experience, to communicate the above results in an issue template that is dense enough that the majority of people ignore it. What follows is either non-trivial time wasted by a maintainer to manually perform the job of the issue template, or an upset user when the issue gets closed with "please read the issue template".
For the sake of this argument, a "Conversation" is any kind of public text-based communication mechanism. GH discussion, gitter, slack etc. Explicitly NOT a GH issue due to the above problems
Don't use issues for bugs. Instead:
- Raise a PR with a failing test and a fix.
- Don't have the expertise to fix? => Raise a PR with a failing test.
- Not certain if bug and need help diagnosing? => See Conversation and ask for help
- No one volunteering to help, fix, or work on merging the PR? => pay based interaction
Don't use issues for features. Instead:
There are several factors that affect how features should be handled:
- Not sure if will be feature will be accepted? => Raise PR against the docs that outline how this feature would work or start a Conversation.
- Certain the feature will be accepted? => Raise a PR with implementation and docs changes
- No one responding to Conversation, or working on merging the PR? => pay based interaction
Don't use issue for questions. Instead:
- Use StackOverflow or a Conversation.
- No one responding? => pay based interaction
@SimonCropp This doc is what persuaded me to have a go at creating a PR:
SimonCropp/MarkdownSnippets#288
That was my first ever C# commit - and it took a couple of goes to set up a working environment - but then for me, the test was easy to creating, and the whole thing was ridiculously satisfying...
Just thought you might like to know that it helped at least one person!