Collaborating on open source

This article was first published on Medium.

Using open source projects has become increasingly popular. The number of companies using open source is growing. Unfortunately, the number of people building and maintaining it is not growing quite as fast.

Open source doesn’t come for free; someone is doing the work. And they could use your help!

Why you should contribute to open source

There are many reasons why you might want to contribute to open source.
Personally, I started because I was looking for a way to learn more about programming, and wanted to do so in a way where I might contribute something useful.

Then, I continued doing it because I enjoyed the collaboration and feeling useful and appreciated. Also, I did learn new things I was able to use at work. Your reasons might be entirely different!

I’ve heard people also contribute to open source to give back to the project or community, to build their CV, to “scratch an itch” (fix a problem they are having), or a variety of other reasons.

Ways to contribute

The most obvious thing you can do is to fix bugs, or add new features. If this is something you can do, please do! Unfortunately, this can take considerable time and coding skill, which not everyone might have. So how can you contribute, if you are not a programmer with lots of spare time?

There are many things that you can do that don’t involve coding and don’t (have to) take a lot of time. I have listed some below, along with some examples of my own contributions.

Writing documentation

One of the ways to contribute is by adding to the documentation. This is often mentioned as an easy way to get started. You don’t need to know how to code to do it; you don’t even necessarily need to know a lot about the whole project (depending on the change).
If you are adding content, you do need to be able to write well, and articulate ideas clearly. Other skills that might help are attention to detail (like spelling and grammar), coming up with good examples, etc.
Even if writing is not your strength, there are still many ways in which you can help:
* Read documentation to see if it is clear and complete. If not, offer suggestions on how to improve it. Or at least inform maintainers what is unclear to you and why.
* Fix small things, like typos or dead links, if you can. For example, some small contributions I’ve made were fixing a dead link in the Docker documentation and fixing a typo in a Pitest error message.
* Let maintainers know if you find typos, dead links, mistakes, outdated or missing information. It’s really hard to keep a fresh eye on documentation you might have rewritten and edited multiple times!
* Add information that is missing, especially if it is something you had to find out for yourself (either with or without the help of the community). Someone else might have the same problem.
* Add (links to) relevant blog posts. If the blog post is your own, consider adding relevant information from your blog post to the official documentation also. You can still offer a different perspective in your own blog.
* Review any open PR’s (pull requests) on the documentation. Look for the things mentioned above: it is clear, complete, correct? Do you see any typos or other mistakes? (Have I mentioned it’s hard to spot typos in something you’ve been working on for a while?)
I, for one, love getting reviews on my documentation PR’s; the suggestions make them so much better! And I love how this makes each PR the product of collaboration, rather than one person.

And for all of these: if it is something you can do yourself, please do so!

Answering questions

As a user, you can probably help other users with problems you have faced before. Remember, someone probably helped you in the past in one way or another. Share what you have learned!
And if you notice a lot of similar questions, consider adding to the documentation. We have recently added a FAQ page to the Cucumber documentation, and would love additional contributions to the page. Other projects probably will too!

Creating an issue

The least you can do if you encounter a problem, is create an issue. Maintainers might not all use the project in the same way, and might not be aware there is an issue unless you tell them.

Before creating an issue, please check that there isn’t an open issue for the same problem (prevent duplication). If there is, you might be able to add additional useful information to that issue.

If you are not sure you have found a bug, please contact the community to ask them. Most projects will have one or more ways for you to ask questions (Gitter, Slack, mailing groups, etc). It will often be quicker to get help that way, as more people in the community can help you (not just the maintainers who monitor GitHub issues). This might also start up a dialog on what the exact issue is, how to reproduce it etc. which will make it easier to fix.

When you do create an issue, please be as specific as you can and provide sufficient information to help maintainers understand and reproduce your issue. Many projects use templates requesting the type of information they need; make use of them! Or, if they don’t use a template yet, maybe you can add one to the project?

And again, if it is something you can fix yourself, please do!

Reproducing issues

When someone opens an issue, a maintainer needs to look at it to understand the problem. This is where you can help! Is the issue clearly described, and does it contain sufficient information to reproduce the issue? If you can reproduce it, you might be able to provide additional helpful information.
And if you can’t, you could ask the original author for more information. Or maybe the issue can be closed!

Add unit tests

If you know how, you could try to add a unit test that reproduces the issue, which both shows there is an issue and will help getting it fixed. And if you can, fix it yourself. My first contributions to Cucumber-JVM were unit tests; the first one to show that a particular (old) issue had already been resolved, and another to reproduce an issue. Fortunately, I was also able to fix it too!

Labelling issues

Many projects on GitHub use labels, to signify the type of issues. Which labels are used will vary per project, but using labels can help people either find an issue similar to theirs (preventing duplicate issues from being created), or help people find issues they could contribute to.
Adding the right labels to issues can help both maintainers and users of the project, and is something other maintainers might not have time for.
Note: as far as I know, you do have to have access to the project to be able to add labels, so this is not something you can do when you first get started.

Review PR’s

Reviewing incoming PR’s can be a lot of work. If you are not too familiar with the code base, you might not be able to say anything about the overall usefulness or direction of the PR, but you might still be able to help. For starters, you could check the readability of the code, see whether the test coverage is good, look for typos, etc. Alternatively, you might be able to build the branch locally and test it yourself to see if it solves whatever issue it was designed to solve. Even if you can’t read code, you can probably still review documentation PR’s (see above). Reviewing PR’s can also be a great way to gain experience with reading code, and to get to know the project better.

Testing new features or versions

Maintainers and contributors don’t always have time to extensively test new features or versions. This is where you can help! Create a new project to test the new feature, or upgrade your existing project to the new version (even if it is still in development). Provide feedback to the people who are working on it.

Note: there might not be open issues registered for test work. That doesn’t mean it’s not needed! You might hear about test work that is needed, when you become a more active member of the community. If this is something you’d like to do, but you are not aware of anything that needs testing, ask the community! Even if they don’t have anything right now, they might ask you in the future.
For example, when Cucumber expressions were being implemented in Cucumber-JVM, I tried them out with a small sample project and reported my findings to core maintainers, as well as made some notes on things that should be added to the documentation.

Cleaning up code

Projects might also benefit from refactoring or cleaning up code. There will be plenty of ways the code could be improved, especially if they have been developed over several years by different developers.
One of the PR’s I did on Cucumber-JVM recently, was to make use of a parent pom.xml. This removed a lot of duplicate dependencies from the project. While doing this, I also learned more about Maven, which I have since been able to use at work.

Upgrading dependencies

If you notice a project is using outdated dependencies, see if you can upgrade them. Especially, if the older versions contain security vulnerabilities. Note that some projects might introduce breaking changes, so always make sure that the project still works with the upgraded dependency. For example, I have updated Jackson dependencies on GraphQL, due to some security issues found in older versions of Jackson.


There might be other ways for you to contribute. Even if you’re not a programmer, you might have other skills that are valuable to a project.
If you do have ways to contribute that are not mentioned here, please let me know in the comments!

How to find a project to contribute to

There are several ways to find a project to contribute to.


If you have no idea where to start, there are several websites that list projects looking for help:
* GitHub itself offers some suggestions on choosing projects.
* Have a look on CodeTriage for projects with open issues
* Look for issues by project, label (like “good first issue”) and/or tag (for example, your preferred programming language) on Up-for-grabs
* You can also find these links and more on First Timers Only

Projects you use yourself

A great tip on where to get started, is to help out with a project you use yourself. You’ll be more familiar with this project, and you might even be able to solve your own problems. If you are already be part of their community, you’ll have a better idea of what is needed.

Focus on welcoming communities!

Focus on projects that welcome new contributors. Some of the following might help:
* See if there are any issues marked “first timers only”, “good first issue” or something similar; this would signify they are open / looking for new contributors and give you an idea of where to start.
* See how they respond to issues created or PR’s opened (do they ask for more information in a polite or a hostile way, how constructive is feedback on PR’s or issues)
* Check to see if there is a code of conduct, contributing guidelines or things like that (and whether they are enforced)
* Join the communication channel(s) to see how the community interacts

Know that there are plenty of projects and communities out there who would love, love, LOVE your help! And I hope you find one, if you are looking.

Personally, I was very lucky to find the Cucumber community, who were very welcoming and helpful. When I first started, I accidentally merged something that shouldn’t have been merged yet. Unfortunately, I didn’t know a lot about Git yet, but several core maintainers helped to fix the problem (and were still nice to me). I spent the weekend doing Git tutorials, so this would never happen again! Learning more about Git has been very helpful at work; I’m even able to help out coworkers at times.

Reasons not to contribute to open source

While there are many reasons to contribute to open source, there might also be reasons not to do so.

Employer or contract doesn’t allow it

This might be a valid reason for you not to contribute, especially to the code. You might still be able to help the community by answering questions from other users, sharing your experience, creating issues or adding relevant information to them.
If your employer uses open source projects, they will also have an interest in keeping the project maintained. Instead of letting their employees contribute code, perhaps they could become a sponsor? Cucumber, and several other projects, accept donations through OpenCollective; others use Patreon, or other options. Recently, one of my coworkers donated his education budget for the year to an open source project he uses at work. I think that is a great idea!

Being a noob…

Please don’t underestimate the value of a fresh pair of eyes! Documentation, especially beginner tutorials, should be easy to follow along even for people who are new to the project. The project itself should be easy to use. If they are not, this is your chance to provide valuable feedback!
If you are having any problems when using the project, contact the community and let them know. And if they take the time to help you out, why not document what you have learned for the next person who comes along?
Even if you are not having any problems right now, you can still read the documentation and provide feedback (see above).

Not sure this is a bug, or how to fix it

If you have a question, please find out how to contact the community. Many projects have an active user community willing to help you. If you’re not sure you’ve found a bug, just ask them. They’ll let you know whether you should log an issue. They will also ask you for the information they need to fix it.
If you want to add a feature but don’t know how, there might be people to help you get started. They could point you in the right direction of where to make the change, or provide insights on where the project is going.
Proposing your change before doing a lot of work on it, will also prevent you from building a feature that might not be in line with the direction the project is taking.

Don’t have time

Again, fair enough. You might have other priorities in your life.
Not all contributions have to be big or take a lot of time. There might be small things you can do. You might be able to do them at work, if they are related to your work (and your employer allows you to!). Even engaging with the community, by asking and answering questions, or logging issues, can be very helpful!

Come collaborate with us!

Open source software isn’t free — someone else paid for it.

However you are using open source, and however little you feel you have to contribute, there are plenty of small ways you can make open source better.
I hope I’ve given you some ideas to try. Please go and find a way you can contribute to your favourite open source project!

Overview of cucumber community
Cucumber community