Etiquette in open source projects

Tony George
6 min readJun 11, 2018


I have been creating open-source software for many years now. While I enjoy writing code, it’s the kind of people that you sometimes have to deal with, that can make things unpleasant.

There are a lot of wrong ideas among users that can create problems. From asking for ETAs for feature requests, to sending emails asking for help with issues — there are a lot of things that should be avoided.

Following are a few points that should be kept in mind while reporting issues, or requesting features for an open-source project.

  1. Reporting issues by email— Avoid reporting issues over email. Replying to emails take up a lot of time and it’s not productive for me. Even if I respond to your email, I’m likely to forget it in a few weeks, and the issue will remain unresolved. Use the project’s issue tracker to report issues. Issue trackers help users to search for existing issues, comment on the problem, and contribute to the solution. If you need help urgently, consider making a small donation before you send an email asking for support.
  2. Not checking the issue tracker— Before creating a new item in the issue tracker, do a quick search to see if an item already exists for the topic. Most common issues would have already been discussed. If you cannot spend one minute searching for an existing topic, do not expect me to spend 10 minutes answering the same question again. I’ll simply assume you are lazy and move on to other items.
  3. Not reading documentation — Developers hate writing documentation as much as you hate reading it. But they exist for a reason. Go through the documentation (if it exists) and see if it answers your questions. Do a quick search in Google. You will usually find the answer you are looking for. Also, do not bug the developers for documentation that doesn’t exist. Make a request in the issue tracker and leave it at that.
  4. Not providing enough info — Provide details of what Linux distribution you are running, and what you were doing when the issue happened. Every Linux distribution has its own quirks and oddities. Knowing whether you are running Ubuntu 18.04, Manjaro, or something else, will help in understanding the issue. Attach screenshots if possible - a picture is worth a thousand words.
  5. One-line issue descriptions — Just because you are facing an issue doesn’t mean everybody is facing it too. Provide as much detail as you can. Do not assume that the issue is obvious. It sometimes take more effort to investigate an issue than it takes in fixing it. Any extra information you provide can save a lot of time.
  6. Not respecting people’s time — Do not assume that there are a team of developers behind every open-source project, waiting to respond to your queries. Many projects start as hobbies and may have only a single developer working on them, without pay, in their personal time. All projects hosted on my GitHub page are non-commercial and I’m the only person working on them. I spend a few hours on weekends if I’m in the mood for it, and if I don’t have anything better to do. I do not get paid for my time, and I get little by way of donations. I work on these projects because they are useful to me and I enjoy writing code. I will stop working on them when they are no longer useful to me. Sometimes an application may reach a state where it meets all my requirements and I won’t have a reason to continue adding features to it.
  7. Being impatient or rude— Please be polite when reporting issues or asking questions. It may take me a long time to respond to some questions. I have other things to do with my time, and I have no reason to respond to people who are being impatient or rude. If you need immediate support for issues, consider using commercial software where you are actually paying for the support, and where companies producing the software can afford to employ people to provide support for you.
  8. Asking for ETAs — Avoid asking for ETAs for issues and feature requests. It’s more rude than you may realize. People working on open-source projects are not your employees. They have no obligation to implement every feature you request, to fix every issue you report, or to provide technical support that you are not even paying for. I do not enjoy spending my time working on features that are of no interest to me, or investigating issues that I never face. If I fix such an issue, it’s usually because I’m curious as to what’s causing it, or because that issue is affecting a lot of people and can be fixed quickly. The same goes for feature requests. I may add a feature for the sake of completeness, because it’s interesting, or maybe because it’s easy to implement. If it’s time consuming then it will remain undone till I find the time, or till someone else comes along, implements the feature, and submits a pull request.
  9. Expecting quick answers and quick fixes — There are applications that I have not touched in over a year. Even I don’t remember what the code does. Even if your question is simple don’t expect that the answer is easy. I may need to go through the code to see what it does and answer your question. Depending on how much time I estimate it will take, your question may remain unanswered for a long time. The benefit with open-source is that you don’t need to depend on the developer. You can download the source code and start working on the problem yourself.
  10. Offering donations for work— Avoid offering donations for fixing issues and implementing features. The feature you are requesting may require many hours of work. Offering a donation for small amounts can be insulting. Most developers get paid much higher wages than you imagine. If the developer were to charge you normal wages for the work you are requesting, you probably wouldn’t be able to afford them. You can donate to the project if you like, but avoid linking your donation to any specific issue or feature request.
  11. Asking questions like “Why doesn’t the software have feature X” ? - Answer: Because nobody has written the code for it. Either the feature was not useful to me when I was creating the application, or maybe I did not have enough interest in implementing it. You can download the source code and try implementing the feature if it interests you.
  12. Guilting the developers — I often receive emails from people complaining that a feature they requested is still not implemented, how another application X is so much better, and that they are going to switch to it. Making an argument like this is silly on many levels. I don’t know who you are. You are a random stranger from the Internet. How does it matter to me what software you use on your system? You are using the application because it solves some problem for you. If it does not meet the purpose, I expect you to move on and find something else that meets your needs. You may even try implementing the feature you need and submit the changes back to the project. That’s how open source projects are supposed to work. People take open-source code that solves 80% of their problem, make changes to solve the remaining 20%, and contribute their changes back to the project so that other people can benefit. Sadly, some people find it easier to guilt the developers into doing the work for them, rather than make an effort themselves.

Many open-source projects start off when developers have free time and feel the need to scratch an itch by creating something that they need. Once they publish it online, it snowballs into something bigger when more people start using it. Suddenly they find themselves drowning in feature requests, issue reports, and people demanding their time and attention. They are forced to work more and more, for free, on something that started as a hobby. It quickly turns into a full-time job without pay. Unless developers draw a line somewhere, it can quickly lead to burnout, and they may be forced to abandon their projects.

You can make things easier for the developers who make the software you use, by following the points above. Let me know if you have anything to add in the comments.

Here are some other articles on this topic that I found worth reading:

Why I Haven’t Fixed Your Issue Yet

An Open-Source Etiquette Guidebook

Open-Source Etiquette

How to charge for your open-source

PS: This article is not directed at anyone in particular. Most users that I interact with are awesome people, who send me good ideas for improving my applications. Thank you all for your love and support :)