I remember when I had no open-source projects and I had never even heard of Github. To me, the maintainers of open-source projects were mystical beasts who only existed in ethereal form over the internet. If I needed to get support for a library, it required hours of Googling, disabling the client-side gateway for ExpertsExchange, and begging random friends over AIM for help. Usually, I would wind up either giving up completely, repeating the process by picking a new library, or applying an awful hack to make the library work for my specific situation.
It was only after I had begun to heavily use Github and Node.js that I realized these mystical beasts were actually real people, who work very hard on their projects, and generally strive for quality feedback so they can improve on their work.
Unfortunately, as I now help maintain and contribute to over 100 open-source projects, I've seen a lot of inappropriate behavior from developers trying to seek support. I think much of this behavior is unintentional. There are not a lot of guidelines for developers to follow who are new to open-source. In this article, I will dive into many of the common issues open-source project maintainers encounter and I will help developers better understand how they can file for a refund on the open-source project they are using.
There are no refunds in open-source
Most people understand this, sadly, some do not. If you are going to take an aggressive or angry approach when filing a request support, you are better off finding a new project. You need to understand that the person you are reaching out to has probably spent 100s of hours working on this project, for free. They do not owe you anything. The maintainers are extending a courtesy by giving away their work for free and then making themselves available to support it.
The point is, you should try and be nice when filing for support. The maintainer of the project has literally no obligation to help you.
Wrong place, wrong time
Want to really annoy an open-source maintainer? Then ignore any communication channels they have setup for support. If they setup a support wiki, send them a personal email. If they setup a Github Issues tracker, email the wrong mailing list about your question. If they setup an IRC room for support, send them direct messages over Twitter. If they setup a mailing list, post your issue to an unrelated forum.
The point is, take the time to actually research if the maintainer has setup a specific channel for support. If they have, use this channel. If you are uncertain, just reach out to the maintainer and ask where the best place to post support issues are.
Maintainers are not psychics
Here is a list of things I do not know: Who you are, what project you are asking about, what software you are using, what operating system you are on, what versions of the software you are using, what your stack traces look like, what you had for breakfast, and what the code looks like that caused your issue.
If you open up a support issue without providing this information, don't be surprised when the only response you get is asking for more information. Also, I probably don't care what you had for breakfast.
Read the f*cking documentation
If the author has taken the time to write documentation, you should read it. I don't write documentation for myself, I write it for other people. If the information you need isn't covered in the documentation, let the author know. They probably will want to add this information so other people don't ask the same question.
If there is no documentation to read, you should ask the maintainer why. If you want to help contribute to the documentation, you might find the maintainer of the project wants to be your new best-friend. If the maintainer is unwilling to help document the project, or assist you in documenting it, you should probably find a new project to use.
Run the f*cking tests
If the author has taken the time to write unit tests for the project, you REALLY need to confirm the unit tests work before trying to get support. Unit tests help provide a common way to test and isolate issues in a project. If you are having issues and one of your tests is also failing, it will be much easier to diagnosis the problem.
If you file a support issue without confirming you ran the tests, don't be surprised when the response you get is asking you to confirm the tests are working.
Read the f*cking code
Okay, this is a bit harsh. I don't expect everyone to read every single line of the code for a project they are trying to use, that isn't very reasonable. What I do see though, is that a lot developers have a mental barrier to actually opening up the source code for the project they are trying to use. They will read the documentation, run the tests, use the example code, but when they are faced with a problem that could be solved through a one or two line change in the source code, they shut down completely.
The point is that you shouldn't be afraid to jump into the source code. Even if you don't fully understand the source code, in many cases you should be able to isolate your issue to a specific block. If you can reference this block ( or line numbers ) when opening up your support request, it will help the author better understand your problem.
If you don't like it, fix it
Does something about a project really bother you? Does the author not care as much about it as you do? Do you find yourself angrily yelling at the nice people at the bus station due to your hatred of that inefficient algorithm you found? Here is a wonderful idea: Fix it.
Developers want to improve their project. If you find an issue, bring it up. If it's a valid concern, the author will probably want to have it fixed. In many cases, the author will consider it a valid issue, but simply not have the personal time or need to address it immediately. This is where open-source is great. Just fork the project and fix it your damn self.
If you fix something, let the author know
Did you actually fix a known issue? Let the author know about it. Not everyone has time to adhere to the specific coding styles for a project, so if you can't do a full blown pull-request, there is NOTHING wrong with opening a pull-request that only has the intention of showing the author how you solved the problem.
On many occasions, I've opened up requests for support in the form of a Github pull request. This way, I am telling the author: I have found a potential problem with your library, here is how I fixed it for my circumstance, here is the code I used for reference. You get extra internet points if you open the pull request with: "I don't expect this pull request to get merged, but I wanted to you show you what I did".
Don't get upset, rejection is normal
This is a follow up from the last section. Don't assume that because you opened up a pull request, that the author will accept it. There are many reasons that a maintainer might choose to not merge in your specific patch, many of which have nothing to do with you. If your patch isn't accepted, try to assume it's for a valid technical reason and not because the author hates you.
If you feel there has been an oversight, it's okay to not give up. As long as you are being logical and open to other people's views, you will find that you might learn something new, or even teach something to the maintainer.
If you don't like a project, don't use it
You would think this is obvious, but it's not. If you don't like a project and have no inclination to fix it, just don't use it. If you feel you are being "forced" to use a project, perhaps you should re-evaluate the life decisions which brought you to this point.
There are no refunds for open-source. If you go in with the attitude that you are owed something, you will be thoroughly disappointed. On behalf of all open-source developers and project maintainers, I ask you try and be polite the next time you ask for support. Try to remember that there is a real human being on the other side of the screen, and they actually want to help you.