Considerations to properly use open source software projects

27 April 2019  —  Comments

I've been wanting to write this article for a while, but it is a subject complex to approach.

Lately I've had some "conflicts" with users in some of the open source software (OSS) projects I maintain, and I have also seen some of the people I follow on Twitter dealing with the same.

Because of that I wanted to share my point of view on what should be the attitude and considerations when using OSS.

Company vs personal

The first thing you have to take into account when using OSS, is that there are two kinds of projects which usually have different goals.

Company projects

It is very common that companies which activity is related with software or make a deep use of technology, publish their own OSS projects.

These projects are usually born from some need the company has had which is not strictly part of their domain.

Thanks to publishing these projects they can find new talent (among contributors), or position themselves in the industry.

It's also quite common that companies provide paid services which are related with these OSS projects, like specific hostings or deployment services, or just consultancy on using them.

Personal projects

There's also projects which are usually maintained by one person, or a very small team, during their own free time.

These projects are created by people who do it mainly because they love to program and want to share something they have done.

The goal here is to get some visibility, show some skills, learn something new and contribute to the open source community.

While the main purpose is not usually getting money, they frequently accept donations and sponsorships.


Now we know the two main groups of OSS projects. Sometimes we think they are the same, but company projects are usually maintained by people which is paid by a company, and do it during their working hours.

On the other hand, personal projects cannot get that much attention and resources, so they cannot progress as fast as the company ones.

Considerations

That said, when we want to use an open source project or contribute to it, there are a few things to take into account.

Always be polite

While using a project, you will probably end up finding something is not working as you expected, or you'll develop a new need for which the project does not provide a solution.

When reporting bugs or asking for new features, always try to be polite. Provide as many details as possible, be descriptive and help maintainers reproduce the issue.

If you are asked to do some tests and get back with the result, try to find the time to do it. You may think that's not your work, but the issue will get solved much earlier and you will avoid frustrations.

There's a formula I like to use when reporting issues, which consists in filling this template:

  • I did [action].
  • I expected [behavior] to happen.
  • Instead [other_behavior] happened.

This will simplify maintainers see the user's intention, and detect confusions which are not actually bugs. Helping the user use the tool will be easier this way.

Don't take anything for granted

Just because you open a ticket, does not mean the team is going to work on it right away. There are several reasons that could delay it.

  • The project has other priorities.
  • It's hard to reproduce.
  • There's no one available to work on it.
  • Maintainers just want to spend their time in something else (specially in the case of personal projects).

The people working in the project is usually dealing with a much wider scope than you might think, so you have to be patient and understand this.

It could also happen that they don't really want to maintain what you proposed, even though it's a supper critical feature for you, but a project will never be able to cover the 100% of use cases.

Consider contributing

One of the main principles of the open source philosophy is collaboration.

If you have been using an OSS project, the best way to show some appreciation and collaborate with its continuity is by contributing to it.

There are several ways to contribute.

  • You could improve the documentation,
  • You could provide some PR fixing some bug or improving the code.
  • You could provide some PR with some new feature.
  • You could make some economic donation or sponsorship.

The last one is very rare, specially among individual users, but if your company is taking advantage of an OSS project, you should consider it.

For the other three cases, if there's something you think you can help with, there's something to take into account in relation with previous point. You should always ask first.

Maybe someone is already working on something similar, or the team has some ideas in mind that could be shared before starting any implementation, or, as I said before, maybe they just don't want to maintain it.

If you ask first you will save yourself some time and frustrations.

Follow the project rules

All projects have rules, and I'm talking about any kind of rule. How to write issues, the code of conduct, the coding standards, the amount of people that need to approve a PR before merging it...

You have to always follow these rules. Don't try to enforce something just because you consider it better.

If the project requires the use of spaces for indentation but you used tabs because you like them better, don't get mad if maintainers don't want to merge your PR.

Don't take it personal

And finally, because of the reasons exposed in previous points, there will be decisions you don't like.

Don't take it personal, because it's not in most of the cases.

Your issue could be closed because you didn't follow the issue template, or because they asked you to check something and you didn't give any feedback after some days.

Understand this can happen, and you can always be polite and open a discussion, but never get mad and accuse the team to be unfair or treat you in the wrong way.

Conclusion

This article describes a set of rules that should help people using OSS projects and people maintaining them to understand each other, but focusing on the former.

I will try to write something similar but focusing on how maintainers should behave. We obviously forget some times that there's people trusting on us when using the software we write.