Skip to content

Instantly share code, notes, and snippets.

@nzakas
Created June 30, 2016 18:47
Show Gist options
  • Save nzakas/bb025e31583076241d9bac8caee4ba82 to your computer and use it in GitHub Desktop.
Save nzakas/bb025e31583076241d9bac8caee4ba82 to your computer and use it in GitHub Desktop.
An overview of my pain points with GitHub

GitHub Pain Points

This is my feedback on using GitHub to manage a popular project (ESLint). Topics are presented in no particular order. In general, everything I say about issues also refers to pull requests.

For each problem I've suggested a solution. I realize that actually building out a solution is a complex process and my suggestions do not reach the level of detail sufficient for implementation purposes. It's just to give you an idea of the direction I'm thinking.

Problem: No good way to distinguish new issues from "accepted" issues

Users are opening new issues every day, and these issues automatically bubble to the top of the issues list by default. We do label issues that we're committed to doing as "accepted", but if there are enough new issues, you don't even see those until the second page of issues. Why is this a problem? In a word: distraction.

Almost every day I go to the issues list intending to work on something specific and then get sidetracked because I see 3-4 new issues at the top of the list. The extra step of needing to filter by the "accepted" label is not effective at solving this problem.

Possible Solution: A kanban board where issues must be explicitly added to the board by a team member so new issues don't show up there automatically. That would also allow us to easily see which issues we should be focusing on now, which should be next, and which need review.

Problem: All notifications are mixed together

In order to keep my sanity, I've had to turn off all notifications except for when I'm mentioned specifically. I use the notifications page most days, but that can also be overwhelming when there are dozens of notifications to look at it. There's no way to tell the difference between a new issue/PR, an issue I'm actively discussing, or an issue that someone mentioned me on. Additionally, once I click through on a notification to the issue/PR, even if I just decide I want to work on it later, that notification is now removed from the notifications page so I need to use some other mechanism to remember to go back to it.

Possible Solution: Replace the notifications page with a dashboard that separates notifications into new issues/PRs, issues/PRs I'm discussing (as in, I have already commented on them), and mentions. Each of these notifications shouldn't disappear until I explicitly remove it from the page. (GitLab has a similar concept: https://about.gitlab.com/2016/03/02/gitlab-todos-feature-highlight/).

Problem: Limited instructions for new issues/PRs

While issue templates helped, it forces me to decide what the most important issue type and focus on that. Otherwise, I'd have to write a long bit of text that no one reads to say "If it's a bug, do this; if it's an enhancement, do this." Right now, we have the template for bug reports and ask people to go to another URL if they want to report something else. Not surprisingly, people tend to just delete the issue template and type whatever they want instead. That leads to more time we need to spend asking for the relevant information. Barely anyone actually clicks through on the contribution guidelines message, as well.

Possible Solution: A customizable dropdown on the "new issue" page that automatically fills in the appropriate template for what the person is reporting. For ESLint, we'd want to be able to have options for: Possible bug, new rule proposal, new rule option proposal, new CLI option proposal, documentation change, or other. Those could be tied to templates in the .github directory.

Problem: Lots of duplicate issues filed

The setup of GitHub issues encourages people to just file new issues without doing any sort of search for similar issues first. And since no one reads the contribution guidelines message linked on the new issue page, we are end up wasting a lot of time on duplicate issues.

Possible Solution: Add a note directly on the new issue page asking people to search for already existing issues first. Maybe even throw a search box next to that note to make it easy. Or to be really aggressive, optionally allow repos to specify that users must complete a search before being allowed to open an issue.

Problem: Ghost issues

As our issue count has grown, we've ended up with more issues waiting for response from the original reporter or conversation just trails off. It's really easy to lose track of these issues since they do not show up in notifications unless someone interacts with them. Those issues end up getting pushed down the issue list as new issues are opened and can easily be lost.

Possible Solution: Add an optional timeout for issues where if there's no activity for a set amount of days, the issue is either automatically closed with a customizable message or just create a timeout notification to remind maintainers to review the issue again. (A timeout notification plus webhook for issue timeouts would also let us programmatically close issues if we want.)

Problem: No good way to easily gather votes

While the reactions feature is nice, it mixes together all users (team members and non-team members). That can be problematic when you're trying to determine whether or not to implement a suggestion. Right now, there's no easy way to tell the community "here are the things we need feedback on" and then tally those results. Similarly, there's no easy way to say that an issue needs three +1s from the team to proceed.

Possible Solution: Introduce a formal voting mechanism that lets people +1 issues they want to see implemented, separating out team member votes from community votes. Also, have a way to flag an issue that needs community input and provide a separate page where people can go to vote on them.

@arackaf
Copy link

arackaf commented Jun 30, 2016

Problem: Lots of duplicate issues filed

It's worth noting that Stack Overflow has taken great strides at solving this already. After you type in the title of a new question, you're automatically presented with a list of potentially matching questions for the user to click on.

Everyone benefits: users potentially get immediate answers, and maintainers would be spared dup issues.

@montogeek
Copy link

montogeek commented Jun 30, 2016

@nzakas About the mixed notifications, that pages shows an icon left to the title of the issue/pr
screen shot 2016-06-30 at 14 39 20
yet, is not enough.

About Lots of duplicate issues filed: StackOverflow display a nice list with related questions:
screen shot 2016-06-30 at 14 44 12

@pierr
Copy link

pierr commented Jun 30, 2016

For the templates, you van have a page with links that create sur new issue using a given template.

@mcornella
Copy link

Zenhub has that Kanban feature that you desire. Check it out!

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