Skip to content

Instantly share code, notes, and snippets.

@SimonCropp
Created August 22, 2020 02:31
Show Gist options
  • Save SimonCropp/b9c47885970c2cd13de5cd6f94433915 to your computer and use it in GitHub Desktop.
Save SimonCropp/b9c47885970c2cd13de5cd6f94433915 to your computer and use it in GitHub Desktop.

The case for disabling GH Issues

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.

The problem with GitHub Issues

Too generic

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.

(Perceived) Social contract/obligation

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.

Issue templates

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".

Conversation

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

The proposal

Bug

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

Feature

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

Question

Don't use issue for questions. Instead:

  • Use StackOverflow or a Conversation.
  • No one responding? => pay based interaction
@claremacrae
Copy link

Don't use issues for bugs. Instead:

  • Raise a PR with a failing test and a fix.

@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!

@SimonCropp
Copy link
Author

@claremacrae and your PR was perfect. so thanks for that

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment