issues.md

Turning Off Github Issues

My friend Michael Jackson turned off github issues on one of his smaller projects. It got me thinking...

Maintainers getting burned out is a problem. Not just for the users of a project but the mental health of the maintainer. It's a big deal for both parties. Consumers want great tools, maintainers want to create them, but maintainers don't want to be L1 tech support, that's why they burn out and everybody suffers.

The solution is to get more people involved, but how? Some of us think that letting people open issues helps. I don't. Most issues opened are bogus: an incorrect module import, not knowing that promises swallow errors and incorrectly assuming it's the project's problem, or they're questions that are already answered in the README or docs.

This isn't a rigorous statistic, but I'm pretty sure these are 99% of the issues on Github.

Issues aren't creating contributors, and they aren't really helping the project's code either. You're either spending time closing bogus issues or you're trying to find other people to do it, either way it's not healthy for any of you.

What if we just turned off the issues tab?

Consider this: issues are for powerless customers. You open an issue with your software vendor because you don't have the power to fix the problem. But programmers, using open source, do.

Pull Requests for Everything

Opening a Github issues doesn't require you to learn anything new, write any code, or even see the source code of the project. If we turn off issues, then the only feedback mechanism is a pull request. Let's explore the only use-cases I can think of for issues, and how they can be handled with pull requests.

Think you found a bug?

Fork the repo, add a failing test. This will encourage devs to learn how to write tests, and in the process, maybe discover that the test passes and something is broken in their app.

Too early in your career to take on writing a test case? Add an example in the repo that illustrates the bug. If you are able to write enough code to think you've found a bug and open an issue, you are able to open the examples/ directory of a project and make a new one that shows the bug. You may, again, find that the bug is in your app, saving the mental health of the maintainers from wild goose chases for bugs that don't exist. Or, you'll make the pull request, the maintainer can run your example and see "ah there is a bug" and then fix it.

Using issues for this doesn't give the developer any new experience and usually leads to the maintainers chasing down bugs that don't exist.

Using a pull requests with a test case or an example gives the developer new experience, puts the project's code into their editor, and validates or invalidates their bug before ever asking for the free time of the maintainers.

If we want to include more people in open source, I can't think of a better way than getting open source code on their machines and into their editors.

Want to discuss a feature?

Talking about code is often fruitless until there's some actual code to talk about. Pull requests require some code in order to start a conversation.

Write a proof of concept and make a pull request. Nothing is better than code that kind of works when discussing features. It reveals shortcomings of the current code and helps everybody understand better what it's going take.

Don't have time or know-how to write a PoC? write some tests that illustrate the feature. You don't need an implementation, just write some assertions that show the API you think would be good. Or, write an example that doesn't work. These options let everybody involved know exactly what you're trying to do and the conversation will go way faster.

It's social coding. Let's have our conversations start with code, working or otherwise. Let's build up contributors by getting some OSS in their editor, and get them writing some code.

Have a question?

Okay, we can't do pull requests for this. But issues are a terrible place for questions anyway. Read the docs, read the examples, go to stack overflow. Questions aren't issues.

Whatever community of folks answering questions you want to build you can build on a platform designed for it. Maintainers can look at the questions over there to get a feel for where their documentation is lacking, but you don't need the issue tracker cluttered up overwhelming maintainers. Turning off issues forces this optimal scenario.

Issues might still be useful for bug tracking, like @spudly said. I though about a possible workflow:

found a bug ->
- pull request with failing test (using semantic-release)
- Travis build fails, automatically create issue with details
- Use issue to track/discuss the bug

Then the post build process that creates the issue can have a defined format (how to structure the issue description). Any issue which was not created by the build process (someone manually created it) is automatically closed, with a reply explaining about how to contribute, e.t.c.

This came up because i remembered of people who are beginning in open-source trying to find issues which are labeled easy/beginner/quick e.t.c, so it's good for them and for bug tracking.

Ha ha, closing issues would be the worst that could happen with a project.
"Closing issues" = "Project death"

Don't want to answer to issues yourself?
Give others the privileges.

By closing the issues you are performing FASCHISM.
It's a free society!
It's a free country!
No more totalitarian project owners!
THE CODE MUST BE FREE
OPEN SOURCE MUST BE LIBERATED

I think creating Issues and getting contributors are 2 different things, because 1 is creating Issues and the other is getting contributors, wow ... mind === mindStates.blown

Got linked here via @knowbody's new repo.

My experience with smaller libraries actually is the opposite here. I'm very happy to get issues (even useless ones) on small repos. They're a net value-add to me, even when they just create more work and don't come with fixes.

Why? Because I find a lot of value in discussing use cases with users. I look at questions on the code and usage as being opportunities to refine immature packages. Often I'm not sure that I'm doing the right thing, and even without code contributions, just questions, really what we might otherwise dismiss as "useless" issues are very useful because they point me toward rough spots in my API.

Also, if the package is small and immature, I don't necessarily want my users to submit unsolicited PRs. Maybe there are things in my roadmap that I haven't written out, or considerations that I haven't fully shared yet, whatever – I don't want to force people to write out a fully coded solution, when especially for smaller libraries, discussion is actively valuable. This is like the Stack Overflow XY problem – in talking through things with the user, I can find better general principles, that maybe are cleaner or accomplish more than a strict "fix".

Moreover, you're not going to get away from being L1 support for libraries where you're the sole maintainer anyway.

For large, mature repos, these things don't hold, and I think the problems with GitHub issues are more visible, but I've gotten a lot of use out of GitHub issues on smaller repos.

Questions aren't issues.

Strongly disagree. It does depend on the quality of the dev in question and isn't always like this, but very often a question is a bug report of "your docs suck" in disguise.

Trying to send a PR to this gist :-/

Spreading topical discussion around the web is a different kind of waste. It would probably be best if Question was just an issue type, and maintainers could unsubscribe to that type. Contributors could recategorize a Bug as a Question. It would not count toward open issues and would drop off your radar.

This probably highlights a good opportunity for Github to incentivize participation like StackOverflow does with their karma. This could be through the emoji system already in place.

I don't share the same point of view. I understand the possible maintainer burnout, but close the ability to open / comment issues is counter productive. You can found a bug on an OS project but don't have the ability or the time to fix it.
With "issues", you can share this information / experience with other users and potential contributors, especially people will who can fork the repository to fix theses bugs on an abandoned repository.

Example: Speedlimit is a preference pane for macOS to limit the system network bandwidth. Since 2013 the repo owner has stopped working on it.
With OSX 10.10 (2014) the lib used has been depreciated/replaced. This things I've found, but I don't have the ability to compile macOS projects. I just open issue for contributors you can add more details and fix that issue or found a workaround.
Today @jlongman fix that issue with a fork.

That means even if you can't work anymore on your project, because it's open sourced, anybody can work on a fix, even years later.

Might be worth having a known bugs document of some sort... every project I've ever worked on has them. Without issues to document them I see it being difficult to coordinate contributors working on them.

Also hard for me to know if what I found is already being worked before I put in the effort to write a test and start a PR. Because I wouldn't see any documentation of the bug until someone else opened a PR. Could result in some wasted effort on the behalf of contributors.

I'll be watching with great curiosity though to see how it works.

@braco:
While I understand where that is coming from, that does prevent experienced coders from being able to contribute without first investing in their karma. It is one reason why I am not an active participant in stack overflow beyond finding the occasional answer to my question there.

Most issues opened are bogus: an incorrect module import, not knowing that promises swallow errors and incorrectly assuming it's the project's problem, or they're questions that are already answered in the README or docs.

This seems like an issue with the way that we provide documentation and not with issues themselves. I think that documentation is the thing that github does worst right now (Not searchable, scattered among various readme files, etc).

If a maintainer don't want to be a L1 support, likely is not listening to their prospect users. A project that do not enforce documentation and communication with their users, will die soon or later.

As developers we often think we know what most users needs are, the true is that is totally wrong.

Issues aren't creating contributors, and they aren't really helping the project's code either

Issues is what you help to build a better product, create trust with users... and Issues will help project code as far as maintainers are willing to understand the root cause of the issues: better/missing docs ?, enhancement requests ?, silly issues because of lack of CI ?, etc.

In the other hand, having issues means people is using what you are building, a strong reason to keep up the good work.

This might work if your project is large enough and/or mature enough but consider something small or something that caters primarily to end users who just use the binaries you create.

tl;dr I am glad if it works for you but somehow I feel like there's more to this. Maybe this is an issue with Github issues? How do you want users to submit bug reports? These are questions every project has to ask itself. Here's something by Scott Hanselman if you'd like to read https://www.hanselman.com/blog/ABugReportIsAGift.aspx

FYI Babel moved back to github issues.

I dont agree with this philosophy. This assumes that the maintainer that built the project created it with perfectly logical syntax, and perfect documentation. One thing I have learned, is that software engineers generally tend to not be very good at exactly these two things. Getting rid of Issues means the only mechanism to clear up what is ultimately poorly written or poorly documented code is to fix it yourself via a pull request. If I had time to stop and clean up every bit of code that I have to utilize on a daily basis I would literally be cleaning up the open source libraries that I use all day every day. For an especially confusing project, and in the absence of Issues, I am guessing many people would just opt out of using the project out of frustration.

Additionally, I think the maintainer, who has the domain knowledge seems like the better person to address issues or at least have a first shot at it, rather than someone that has only just started using it and may not be using it for more than a very limited use case. Communicating without issues and just PRs could result in a timely, and largely fruitless back and forth at an unecessary level of detail. You've just pushed the problem over to PR's only you've made it worse because now you have to read through a full PR rather than 2 sentences asking a basic question.

Think of how we approach development in general, we don't validate concepts by implementing them first in code, we discuss first because discussions are cheap, code is expensive. Tests are also cheap (though not as cheap as discussions), so I have no qualms with communicating via means of broken tests, but an issue seems like a more appropriate place for this, rather than a PR which is intended to be a completed change set ready to merge.

We are software engineers but we are also people. Its ok, we can use our words. The maintainer always reserves the right to make a quick response and say "this is really basic for reasons X,Y,Z" and close it, but many times even in these cases I think its a smell for a hole in documentation somewhere.

I don't bother with projects where I can't report broken behaviour.

It will leave a lot of people abandoning this project and move on. Why? Often reporting a bug is way easier than cloning the repo, creating a test case (is this even possible sometimes?) or finding and example directory (most projects don't have one) than just writing down what an issue there is.

How is this going to help developers if now 10.000 people clone your project and create random pull requests. I think this will higher the load of work for developers even more with tons of useless and senseless pull requests for pretty much everything.

Bug trackers exist for a reason.

via https://twitter.com/benoitc/status/867249881659973632

not sure if it's better than having to reject prs because you're not interrested in supporting a feature

Cannot agree with the idea behind this more. Like said, any suggestion or bug can have a contribution as starting point, be it just a testcase, documentation example, README entry. This also opens up the road for documentation/design/test first development and makes people actually look at your docs and tests (also a pet peeve of mine).

As @kentcdodds mentioned, this pattern stands or falls with proper documentation in the README (link to CONTRIBUTING.md). As this is the first (only) page users see there should be a good funnel to direct them right way for this project. Otherwise they can only fall back to known pattern like going to stackoverflow or giving up. Not everyone is fluent in 'Github'.

I have to disagree with disabling the 'Issues' tab. Maybe instead putting enough information and the expectations people can have in the issue template. This way you keep the door open for people who just don't know how but still want to contact you but you do not have to be the rude person when closing trivial bug reports. As open source projects are mostly voluntary my opinion is the effort should come from both sides as much as possible.

There is still one loophole though, using --allow-empty to just create an empty commit and dump the 'issue' in the PR description ;).

Issues is what you help to build a better product, create trust with users

I do not sell my open source libraries and applications, so they are not a product. I don't care if users trust me because I don't need them to buy my code.

Interesting idea, but it won't work well in a lot of cases, especially if there are not contributing guide or documentation around.

@cweiske remind me not to use any of your repos. Maintainers have to realize that while they are spending a lot of time maintaining, they are also asking those who use their libraries for a lot of time because they have been sold into the process of using their frameworks which in some cases may be a huge time investment. Therefore, the users have to be sold on using your "product" and their purchase is with the currency of time. In exchange you get free engineering help, and community notoriety.

I dont like this attitude that the maintainer doesn't owe anything to those who are using the code, without fans the project would go nowhere.

Forcing the onus of support onto the end user isn't a winning idea. It breaks abstraction and will cause a reduction in user base.

A freakin' option to have a warning/disclaimer/whatever as a banner at the top of GitHub Issues would also be a good starting point...

Code is clearer than anything else, but I think somewhere for asynchronous discussions is still needed for fast communication.

Why turn them off? Who's making you read through them or reply to each one? Issues are not meant for YOU alone.

• They help new potential users assess how useful this library is for them.
• They are for other maintainers or power users to give replies. Those maintainers or power users might have a better grasp at the source code than the user who submitted the issue and they might submit a PR to fix it. Or they might point the user in the right direction so that he can try to fix this issue himself.
• Have you ever googled or searched through project's issues for an error message that library spitted out? I know I have. Users don't always have time to dive deep into the library's source code. What should they do if issues are gone in your opinion?

You actually can(I know that's a huge secret) ignore stuff on the internet. You can ignore issues if you want. Other people who maintain or use this project might not want to ignore them from time to time.
Or you can enforce the quality of issues by closing them if they don't provide a test repo or proper description and reopening them when they do.

I've seen projects that closed issues under false pretense of encouraging people to submit PRs. These projects now have multiple open PRs just hanging unanswered because without issues there was no feedback, no confidence that there were people(besides other maintainers) using it and the maintainer completely lost interest in this project or OSS. Or maybe he closed issues because he had begun to loose interest in OSS in the first place...

Either way I think you just fool yourself when you say it's a useful step that's going to help you avoid burnout or encourage contributions or whatever.
It's the same as you would block google search for the name of your library or block tags that relate to it on stackoverflow if you had this ability because of "burnout" or in order to encourage PRs. Ridiculous.

As a former total noob that stumbled on all of this years ago trying to get sticky windows on my mac. I could handle writing tests for lots of problems i've encountered with OSS, but I've never written a test. Tests are something professionals do, beginners these days don't hear any talk about testing freecodecamp and eloquent javascript and even sicp dont go into it. I've picked up some books on the logic of programming to help me build systems, but I am still far from considering myself fluent in anything from this rabbit hole i'be crawled into.

Github is too involved for most, and Stack Overflow is too discontinuous for some serious edge cases.

As an example, I have spent countless hours studying the bcma b43(BroadCom) frameworks for linux boxes. I could probably, with social coding, try to fix my own issue and learn a shit ton about wiress network interfaces in the process.

Which would connect very well with my studies into radio.

I guess the first question you need to answer is who you write the code for? Do you just share with the world for the good will (why waste code laying around with no good use to you, maybe it helps others), or do you actually want to grow a user base (framework wars). I think this idea is great for the former, but might not be suited for the latter. I think what you really want is just disable notifications, put a disclaimer in the readme, and fix bugs when you actually get to it next time you need the package. I think we burn out striving for perfection, we just need to accept that we are human and move on. I think we need to learn when to stop, it's good enough that we make our work available for free.

I think Github is not like any other ordinary website. It is a huge reference for many programming and other issues. Of course it is up to the person himself to turn off the issues. But for myself I don't because I want to know any new idea or opinion or point of view about the issue.

What if a user does not know the language? You can get valuable info about bugs from nonprogrammers filing issues, even if the useful ones are a minority.