Have you ever found yourself working on a project, stumbling on a neat tool, only to discover that the community support for the tool looks somewhat like the 1900 book The Wizard of Oz? You may have stumbled on a Free Software (aka Open Source) project.

What’s Free Software? It’s software where users have the freedom to read, change and redistribute. The license terms usually put more emphasis on the rights of the users. As a result, such projects tend to have somewhat informal communities of people collaborating online.

Well, regardless of how the software is developed, every project is its own little world, culture, with intricacies, oddities and absurdities. This is not unique to Free Software projects, but that will be the focus here. This is a reflection on some types of contributors to Free Software projects, and how, as contributors, can move things forward and become better contributors. It includes random observations and lessons learned. It is, by no means, exhaustive.

So here we are, in a community of people who help random Internet strangers. Similar to Dorothy in the Wizard of Oz, many of us end up walking down the yellow brick road because we want to fix an issue. Along the way we might make friends, some foes, take on new responsibilities and make some interesting discoveries.

Users

First and foremost, we are all most likely users. As someone who helps maintain software, thank you for using it! Most projects will be happy to know that their project is useful to other people, although it is usually not an objective in itself. There is usually hope that some users also become contributors in some way, big or small.

As users, we don’t owe anything to anyone. Similarly, developers don’t owe anything to their users. Unless there is an explicit support contract, software is often shared in the hope that it might be useful. As with most things, it is still worth thinking about the symbiotic relationship between users and developers, to make sure everyone benefits.

Marketing

A small way to contribute back, for example, can be to recommend or help promote the software. Most free software projects cannot compete financially with the marketing budgets of large corporations. Promoting a probably lesser-known alternative can go a long way. It might be a recommendation to friends, to colleagues, or as decision makers, to require that free software alternatives be considered. If the recommendation feels like a risk, feel free to contact the developers and ask if it’s the right fit. If it’s a business recommendation, it might be worth also recommending a support contract, for example.

Other ways to promote the software might be with howtos guides, blog posts, case studies, or Youtube videos. As a non-technical person, there are tons of ways to contribute. Most traditional marketing wisdom problem applies to Free Software projects too, but one word of caution: unless the project has a very narrow scope and features, there are likely groups of users in different verticals, and it can be very difficult to have a website that conveys to everyone’s market. Focus on the core features, and how to get started, and then have a long tail of sub-pages describing more narrow verticals. The front and center of the home page should have a very simple description, and a simple call to action (how to get started).

A last word on marketing: try looking at Google sometimes without an ad-blocker. You might be surprised to see that other projects (usually proprietary/paid products) are buying Adwords so that when people search for your project, they fall on their website. I guess we can take it as a compliment when it happens, but again, it shows how difficult it can be to compete financially. Feel free to shame them publicly, and also, if you can, a few hundred dollars per year might be worth it, even if contributing to this dirty game can be depressing.

Translation

A good website is important, and if the software supports it, a translated website opens up to new markets. Many developers might be used to do everything in English, but to convince users that this is the tool for them, it should speak to them in their language, and ideally, have support forums and support providers in their language, which sometimes only happens when a project reaches a certain level of maturity. Translation of marketing materials is something harder to keep track of, compared to code, because translators might want to build their own website, their own forums, etc. At first, that might be easier, but then as translators come and go, bits and piece chip off, and have to be rebuilt. I think it’s better to plan it from the start, and keep it centralised.

As a translator, convincing the project developers to support translations of code and marketing materials can be an uphill battle. It’s a lot of work for everyone, but it’s usually worth it. Compare the project with the competition. Do they translate? Are there other projects that are specific to certain regions, and “our” tool could easily compete if it supported the language? Then again, as a developer in Canada, if someone uses my project, for example, in Brazil, I will be very happy, but odds are it’s not going to pay my bills. As a developer, I would hope that a community of users in Brazil will eventually also contribute back, either by improving the project, or financially supporting it.

For example, as someone in Canada, but who works primarly on a project that originated in the United-States, features specific to Canada, such as bilingualism or complicated tax rules, are seen as a burden to other developers. Canada is by comparison to the US a tiny market. Then again, there is less competition in Canada (at least in my field). We were able to build a community and contribute back to the project, and help maintain the bits that are specific to Canada, which also happened to be adaptable to other countries as well, pushing things forward.

Financial support

Time and money are two scarce resources, and asking for money often stirs various emotions.

As a user, what is the impact if I donate $20 or $100 to an Internet stranger who develops a neat tool I use? For some people, that might be a lot of money, for others it might be pocket change.

There are a few things to consider: is the project managed by a company, a non-profit, or an informal group of individuals?

  • If it’s a company, small or big, then they probably have a business model in place that we can support. Why support them, if they are giving away their product for free? Obviously, so that it can continue to be free. Many projects will offer support contracts or subscriptions. Other companies might be making money mostly off consulting or customizations.
  • If it’s a non-profit, then they probably have a structure in place to become a member or to donate money.
  • If it’s an informal group of individuals, they might be freelancers, or have their own company, and making money off consulting or customizations. Some developers have a Patreon page, or a Github sponsor page. Depending on their jurisdiction, it can be tricky to accept donations. For example, in Canada, I am technically a freelancer. I cannot accept donations, but I can invoice an amount equivalent to that donation, and I declare it as income, and the donor can declare it as a business expense.

Some projects also have an option to advertise on their website. For example, a project I work on has a “trusted experts” page, where service providers pay a yearly fee to be listed on that page (if they meet certain criteria).

Managing donations for a project requires a lot of work (marketing/communications, accepting payments, accounting). I have often heard “put a donation page up, and we’ll donate money”, and then we put work into it, the page is up, and they change their mind or only give half of what they pledged. There is also a risk of user entitlement, that if money was donated, then we should work on their requests (and usually for a much smaller amount that would have been quoted, had it been a development contract). My point of view is that donations are for work that has already been done. If they want more work to be done, then it should be under some sort of contract.

Of course, disclaimers aside, please do support projects that accept donations!

Forums

On forums where we sometimes find solutions to problems, it’s also sometimes possible to reply to other people’s questions. This is harder than it looks. Odds are someone will reply that the solution is not the best (and maybe they’re wrong), but whatever! It helped move the discussion forward. If you are active on forums, don’t let perfect be the ennemy of good. Be welcoming, patient, allow people to do mistakes, assume some level of misunderstanding, and when in doubt, ignore it.

A few tips on etiquette:

  • Read the room first, see how others interact on the forum
  • Be clear and concise. Odds are that there is a high volume of messages, and people will skim through to see which posts interest them.
  • Help others too, many forums are informally “tit for tat”, meaning that while we are happy to help, we all have limited time, and tend to focus on helping those who also help others, or contribute in other ways
  • Good vibes only. Everyone has frustrations, pressure from deliverables, a sick relative to take care of, kids to feed. Stay technical and avoid drama.

For example, I often see “my client/employer/cat lost a million dollars because of this bug”. Well, bugs suck, and we’ve all encountered crazy situations, and we all have different situations at home. Unless you have a support contract, using the software was your choice. Let’s focus on fixing the bug, and avoid the drama from the client/employer/cat. Going supernova on drama will likely just get you ignored.

That said, getting involved on forums can be a great way to learn things and make new connections.

Testing patches

This is an often overlooked but highly valued task. Testing patches does not necessarily require a lot of programming knowledge. For developers, having someone confirm the bug they found, and that a patch fixed it, and did not cause other problems, can really speed up the time it takes for a fix to be accepted by the maintainers.

It’s also a good way to understand how the code works, especially the parts of the code that are relevant for the features you use.

The fork

Now let’s say we are now at a fork in the road: we have identified something we want to change (a bug or an improvement). Things can get a bit muddy here.

The easiest short-term fix, is usually to fix it for ourself (or find someone who can). We have a copy of the code, we can change it, and we can tweak it so that it fits our needs. It’s an easy fix because we don’t need to worry whether it works for other people, only for us. Sometimes there is pressure to deliver. “I need to get this to work by tomorrow” or “I need to get the job done, I have a project deadline”, etc.

A lot of people (at least in my experience) will fix something for their needs, but will not share their solution. It’s completely understandable. The solution might be a horrible hack. We might not feel confident in our solution and don’t want to look unprofessionnal, or we just don’t have the time or expertise. Sometimes corporate lawyers at work forbid developers from sharing their solution because of fear of patents or fear of giving any kind of legal opportunity to competitors. However, legal restrictions aside, if you can share your solution, however horrible it is, please do! It’s really surprising sometimes who else might stumble on that half-baked solution, and hopefully improve it.

An example of a somewhat recent experience: I wanted to tweak my desktop on Linux so that the top-bar is hidden most of the time, because I found it distracting and using too much space on my tiny screen. After searching online, I couldn’t find a setting or an extension that could do it, but I did find a blog post showing examples of how to do it. The blog post was a bit old and the person seemed to have lost interest. I didn’t know anything about writing desktop extensions, but the blog post was clear enough, so I followed the steps, it worked, and I published my extension on the online extension directory. Someone reported bugs, and we worked together to get their fixes merged in my version. Quickly that person showed that they were clearly more savvy and motivated to maintain the extension, so I gave them the rights to publish new versions. As new versions of the desktop came out, it often broke the extension, and that person fixed it very quickly. Years later, I’m still a happy user, and they are still improving the extension. So by sharing my amateur code online, based on some random examples, I did my small bit to push things forward, someone else did their bit, and now there are many hundreds of people using that extension.

Had I not shared my code, maybe someone else would have come up with a different solution, but otherwise, my amateur code would have broken on the next upgrade, and I would probably not have been motivated to fix it. For a desktop tweak, it’s not a big deal, but if it was a more important tool, I would have been stuck on an older version, or have to spend time finding new solutions. Fixes that are not contributed back to the official project (“merged upstream”) are a form of technical debt, meaning that one day or another, it will have to be addressed.

Be mindful, however, that a solution that works in one situation might not work for everyone and for the project in general. When a fixed is included upstream, the maintainers become owners of the new code. If it breaks, causes problems to other people, they will be the ones blamed, and they will have to prioritise fixing it over their other work. It can be very stressful. So maintainers can be fussy about what fixes or improvements they accept in the official version. It can take time to get those changes accepted. Meanwhile, even if it is published but not accepted, there are chances that someone else might pick it up. As always, no obligation, from you or from them.

So we continue our journey, and try to get that improvement merged upstream.

Merging upstream

Code contributed by the community are definitely considered valuable contributions. They can also lead to friction, if the contribution is not accepted by maintainers. When changes are merged upstream, they become part of the project, and the maintainers become responsible for the code (not legally, but they will get blamed if it fails). Therefore, before putting in a lot of work to propose a change upstream, it’s worth discussing it with maintainers first.

If it’s a new feature, or even a bug fix, maintainers might ask that automatic tests are added, to ensure that the feature/bug does not randomly break in the future, as other features are added. It might also require changes to documentation.

Sometimes a feature might be really neat, but not something that the maintainers need, and it’s purely up to them to decide if they view the feature as relevant for the project. It can be surprusing sometimes how a certain feature could have been implemented using something that already exists, instead of adding an entire new feature from scratch.

Code that is not often used, not well tested or not well understood can be perceived as technical debt. Meaning that it might be at any moment or it might not be easy to fix, and maintainers could decide to remove it.

If maintainers did not signal an interest in getting a new feature merged quickly, it might be worth, during development, keeping in mind that the feature might live as a patch, to be applied on a build (a bit like maintaining a fork). It might be possible to break the patch in smaller pieces and get some of them accepted. In any case, smaller, incremental changes, tend to be accepted more quickly than huge changes that can be difficult to review. If the patch is easy to use, other people in the community might start using it and contribute to the review, and help maintainers decide if it is a relevant change or not.

Becoming a maintainer

At this point, you have probably realized that as we walked the yellow brick road and met the Wizard of Oz (the maintainer), that you too, can be a maintainer. Sure, some developers are truly brilliant, but many are folks who either just happened to land there and doing their small bit to push it forward.

Some random advice:

  • Don’t work for free, or not too much. It can be exhausting and not be rewarding. If people really want something, then they should be able to contribute something (financially or not, it could be help with design, testing, documentation, etc). It can be very easy to get pulled in various directions and lose track. For example, if I get asked “can I do X with your project?”, answering that might require some research. Maybe I really want them to use it, and I will do changes in the code so that they can. Sleep on it, and see if they can finance all or part of the work.
  • Spot the brilliant people, but who also have empathy and care for the project at large. You only need two or three, and it avoids having a project that relies on a single person. Careful for narcicists.
  • Use a decision-making process that you are comfortable with and which seems relevant for your community. It may be more or less democratic. Don’t let it become a burden of politics. Overly democratic processes sometimes start to dictate what developers do, but that only works if the developers are fully funded by those constituents.
  • Ignore or kick-out people who impose their drama on others. You are the good-vibes enforcer.
  • Give the example in how you would prefer other people to behave.
  • Be open to feedback, but don’t let it turn you down. When in doubt, keep the topic technical.
  • Be careful of people who offer to take control of the project. Worst case, if it’s Free Software, they can always fork it and create their own community.

Of course, all of the topics in this article might be subject to heated debate, and can vary a lot from a project to another. I felt like writing about my experiences with contributing to Free Software projects. It’s not always rainbows and unicorns, but I think it’s a rewarding journey, and hopefully it will have motivated you to take the next step in your adventures.