About a year ago, we started looking into ways to document our event-driven Kafka API and decided on using springwolf. We enjoy its capabilities to extract documentation from code, similar like Swagger and springfox, but soon noticed that we need additional features. This is my story about getting into open source.
Springwolf is/was at that point a comparatively small project, which is actively developed and has (semi-)regular releases. It is also a great fit for getting started as there are no long guidelines on how to contribute and approval process. And, the code base is small.
Open Source contribution in springwolf
Back to the feature: We were looking to provide an additional description for each Kafka consumer/producer. On the technical side, this is one additional String field in an existing data structure. The change is as simple as it sounds. Add the field, document it, update the example & tests and finally create the pull-request.
The maintainer (Stav) reacted promptly and welcoming. Moreover, the code made it into the next release. Yay!
Why you should contribute as well
Especially when starting in your CS career, getting exposed to various projects, styles of solving things and ways of work is beneficial to your personal development. There are also more benefits, including these:
Learning: There are many aspects to this.
First, you will get familiar with the project, the code, their contribution guidelines. As you progress, you will see patterns and alternative ways to solve problems.
Later, you will get a feeling for the direction of the project and the use cases it is used for, which might be different to the original idea. Understand what users want and invest energy there. Or declare non-goals - for now - if you see the main benefit in a different area. Sounds much like a product, doesn’t it?
Roles: During these phases, you likely also act in various roles. It allows you to try them out, rotate and you can discover what brings you joy in a safe setting.
Become an expert: You have the chance to dive into whatever you are interested in.
Build your prototype/library from scratch or stand on the shoulders of giants and add this thing everyone has been waiting for to your favorite project. As part of it, you, the |put-your-role-here|, become even more knowledgeful.
Others will help/review/ask questions. Don’t be afraid of it, view it as a chance to learn from the experts. Everyone started in your shoes in the beginning.
Give back: You know the saying: “If you have the question/problem, you are not the only one”. It is the same with (open source) projects. If you can, help someone else.
Together we can build unimaginable solutions. Don’t just copy and use, give (a short) feedback.
And remember, helping others feels great.
Be the community: Connect with people around the globe. Build a shared understanding in a (mostly) remote setting. Chat about any topics. And who knows, you might meet up in real life at a conference or plan a visit.
Be visible: Open source work is open. It can be intimidating, but it shouldn’t. It is a journey to become better, join initiatives, put your name out there and gain GitHub stars - the most valuable developer currency :)
You are in control: In the end, you decide what you can give. There are many ways to contribute beside code. And if you need to take a break/switch the project, just do it.
There are many resources on how to pick a good project. GitHub’s good first issue label is a great on to find open tasks. And in general, everyone is happy even for small contributions like improved documentation.
What to consider for your first contribution
As a first time contributor, you might ask what are the steps and what to watch out for? Here are my thoughts:
Select the right project
Ensure that it is actively maintained and has some activity. Check when the last pull-request was merged. This will give you an impression about how long it will take to get changes accepted.
While big projects are very active, these tend to be stricter. Many simple things (low hanging fruits) are picked up by other in order to say “I am a contributor to Big Project XYZ” (see Be visible). I recommend a smaller project for the beginning.
Read the contribution guidelines
Maintainers usually have limited time and have documented what they expect in contributions. While it might be annoying at first, it creates a shared expectation and avoid late surprises.
A starting point is the
README.mdfile in the project.Depending on the size of your change, you should also open an issue to discuss and get feedback before starting (in case there is no contribution guideline).
Contribute
You know what you want to contribute. Try to match the existing style, consistency is key. This includes formatting, structure, commit message, etc.
Keep your changes small. Even if you want to fix 3 more things, the first PR might not be the best starting point. The pull-request should be easy to understand and limited to a single issue.
The maintainer does not know you. Over time, you build a trusting relationship with the maintainers, simplifying getting large and/or complex changes accepted.
Get your changes accepted
Open the pull-request, explain what and why you changed something. Refer to ticket, if one exists.
Did you include everything? Documentation, Tests? Is the pipeline (in your fork) green?
Just in case, re-read the contribution guideline.
Maintainers might be picky and ask for changes. Work together to resolve them, review comments are written with the best intention in mind.
Maintainers know that they have to maintain features in the future, migrate them, resolve (currently unknown) issues. The maintainer does not know, whether you will be a one-time contributor or intend to get involved for a longer period of time. Also, life might get into the/your way.
So, make it easy to get your solution included.
Celebrate
Congrats, your change got accepted. You are an official contributor now!
Don’t be discouraged when people don’t react/answer within hours. Open source is often - unfortunately - a side project in the maintainers spare time and more a marathon than 100m sprint.
Don’t hesitate, get involved and have fun!