As a user of open source

A couple of months ago I read an interesting article on what it feels like to be an open source maintainer, and I’ve been wanting to write a response ever since.

I found it when the founder and benevolent dictator of Home Assistant, Paulus Schoutsen, mentioned it on twitter, but it applies to any medium sized open source project.

It should be required reading for any potential contributor and even for users. If it doesn’t make you more conscious of how you interact with open source maintainers then it’s either preaching to the converted (and good for you) or you need to read it again until it sinks in.

As a user, the main thing to remember is that those projects started because the lead developer wanted to scratch an itch – they started the project to solve a problem they had, or to play with some interesting new technology. It’s usually a hobby or sideline.

It must be a huge buzz when other people start to get involved and see the value in what they’re doing, but the transition to being both developer and maintainer of a community of users is always going to be hard. Writing documentation, setting up a forum, answering bug reports and assessing code contributions are massively time consuming and less interesting than working on the code.

Be grateful, be very grateful, that they do it.

Remember that these are not like the big open source projects, such as Apache, that have commercial backing and are able to pay people to do the tedious grunt work of documentation. If you’re asking a question you’re asking someone to devote some of their free time to you. Always keep that in mind.

As a user, make sure you get the basics right:

  1. Read the documentation.
  2. Use the forums if they exist, rather than go straight to the developers. Don’t forget to search them first before asking a new question.
  3. Experiment for yourself before you ask a question – try different things.
  4. If you think you’ve found a bug, try to create the simplest possible case to reproduce it.
  5. If you do file a bug report or request, make sure you follow up by answering questions to clarify it and by testing any fixes or features that result.
  6. If you have the skills, read the code. It’s the definitive way to figure out what’s going on.
  7. Always be polite! It applies to commercial software as well, but at least that should have support engineers being paid to deal with your problems.

Finally, get involved. Give something back. Open source is a two way street – you get out what you put in. There are always commercial off the shelf alternatives if that’s not for you… 😉

If you use the forums, take some time out to read other users questions and answer them if you can. As you get more experienced with the software you can help out others going through the same learning curve, even if it’s just pointing them in the right direction with a link to some documentation they may have missed.

That’s why I write blog posts for each step of my Home Assistant setup, and include the technical details. I hope other people find them useful – that maybe something that hasn’t quite clicked from reading the official documentation will become clearer when combined with reading my blog.

That, and participating in the forum, is about all I can do to help at the moment. I’d love to get involved with adding to the official documentation but I can’t guarantee the time and don’t want to make promises I can’t keep. That’s another big no-no for new users and potential contributors – don’t promise anything you’re not confident you can deliver.

As users we should be extremely grateful that people like Paulus share their creations with us. They don’t get enough thanks, so I’d like to end this post with a massive thank you to him and the rest of the contributors to Home Assistant and all of the other open source projects I use.

in Random Musings

Related Posts