Written by Manuel Vogel and Jan Katins
Last week our company-wide open space format Open Friday took place and one of the sessions was called Open source is fun, no need to be shy hosted by Jan Katins, John Nguyen, Manuel Vogel, Martin Müller and Martin Wentzel. This blog post presents the outcome of the session: After giving an introduction about open source it describes different ways to contribute to open source projects and shows some examples from our team members. We explain why we believe that contributing to open source is easy and fun and share what we learned along the way.
If you are wondering what the Open Friday is, it is an Open Space format organized by the kreuzwerker Culture Club that takes place every other month in which all kreuzwerkers are invited to share knowledge, collaborate on new ideas and discuss topics of interest. Anyone can submit a session and fellow kreuzwerkers can choose to join them. Sessions usually cover quite a broad range of topics. This time in addition to the Open source is fun, no need to be shy session, the following sessions took place: Gender equality AMA, Playing with Story Mapping - a hands-on workshop on Miro and a presentation plus demo on Artificial intelligence: letting computers solve problems with neural networks.
But before we dive deeper into why open source is fun, one disclaimer beforehand: Contributing to open source is optional!
https://twitter.com/EmmaBostian/status/1484117024611749894
While some of us find it worthwhile to contribute to open source, both for professional reasons and for private ones, we strongly believe that it is purely optional. This article should not be taken as a suggestion that there is any kind of obligation or requirements to do so. We are aware that most people who contribute to open source projects do so in their spare time, which may be very limited depending on life circumstances. And that there are a variety of other reasons not to do it. Thus, we just want to share our own personal joy and experiences with it. And if someone feels encouraged after reading this - great! If not - great as well!
Introduction
What is Open Source...
Open source is source code that is made freely available for possible modification and redistribution. [...] The open-source model is a decentralized software development model that encourages open collaboration. Wikipedia
For us personally it boils down to
- I am allowed to see and modify the source code
- I collaborate (mostly with strangers) on platforms such as GitHub or GitLab
- I am able to use the software without a license cost, at least for private use. (Which doesn’t mean it’s free: I still have the costs to set up and use it. And of course, I might still choose to support the development of an open source product by sponsoring it. I also need to be aware of the license and its implications.)
... and why would you contribute?
- Get rid of annoying bugs in a sustainable way - Since the world is running on open source™, most of us at some point during our professional career encounter a bug in our code base that is caused by a bug in an open source library. Sometimes it might be easier to implement a workaround in your own code base that solves the issue, rather than fixing the actual cause in the open source library. Sometimes it is impossible to do so or very cumbersome. In most cases though, the solution almost never leads to a simpler overall1 solution and leads to more maintenance effort and headaches down the line.
- Finally get a feature you want - We bet everyone at some point has been in desperate need of a certain feature in a piece of software, which they were using that just did not exist. By implementing it yourself right where it belongs, you might get it much sooner than waiting for the core maintainers to provide it. Additionally - this of course is a rather controversial topic - the maintenance costs get at least partially taken up by the community.
- Learn something new - A lot of open source projects have an amazing quality level and a super supportive and friendly community. Different architectures and programming paradigms, automated tests on multiple platforms, documentation, best practices of how to set up projects: there are a lot of open source projects that excel at such aspects from which you can learn. And of course, with open source you are not limited to your work stack, but you can contribute to projects in new languages and frameworks. Fixing a super small bug in a huge code base in a language that you are not familiar with yet is a great way to start building knowledge in it. Usually you will receive constructive and detailed feedback, which will improve the feature but also your own skills.
- Give back - We are all standing on the shoulders of giants. We all rely on the work done by others. We are likely all using some piece of software that someone developed in their spare time. Contributing to open source is a way to give back to this community. Of course - this is also a controversial topic - a lot of open source projects are backed by companies that don’t need this. And a lot of companies (all?) use open source projects maintained by individuals in their spare time for business critical operations without paying for them. So this is definitely a deeply personal decision to make.
- And last but not least: The warm fuzzy feeling when you accomplished something and someone even thanked you for it :-)
… and what do you need to contribute?
Contributing to open source is not much different to what you do at work: explaining how to use an app on Confluence? If you do it on platforms like Stack Overflow, you are contributing your knowledge to the community. Opening a ticket in the internal JIRA board is essentially the same as creating an issue in GitHub: have a problem, login to the ticketing system, search for already existing issues, open a new issue, describe the problem so that it is reproducible, done. Or develop a feature in a git branch, get it reviewed and finally get it merged? The same process applies to open source projects, just that the whole process happens in the open. So, if you’ve ever done any of these, you already have the knowledge and skills to contribute to open source projects!
… and how do you contribute?
There are lots of ways to contribute to open source software and actually not all of them involve coding. Answering questions on GitHub or Stack Overflow, raising issues or simply just adding thumbs-up or +1 reactions to existing issues is one way of contributing that doesn't even require looking at the code. A great way to get started with a first pull request is by fixing a typo or extending existing documentation. If you are familiar with a certain codebase or product, reviewing or testing pull requests submitted by others might also be a welcome contribution. And then of course there is the actual coding: From fixing bugs to porting code to a new OS to setting up CI/CD pipelines, refactoring parts of the code base, improving test automation, introducing new features to taking over as maintainer of a piece of software used by millions of people around the world.
In the next section, we want to share some of our own examples of contributing, followed by what we learned.
Contribution Examples
The examples shown in this section should show the breadth of what is possible when contributing to open source, and the positive outcomes and warm fuzzy feeling you can get by doing so.
Example #1: Reporting a Bug in pandas
While working on an early version of pandas, our colleague Jan Katins found that it was raising an exception on data, which looked like it should actually work fine. He boiled it down to a nice short reproducible example and sent this as an issue to the GitHub repo of pandas. The maintainer committed a fix on the same day, which got released two months later in pandas 0.9.0.
Thus, by simply opening this ticket, not only did Jan’s own life improve within only two months, but in all likelihood, so did that of a lot of other developers who had never faced this issue before.
Example #2: Add Missing Parts to Spring Cloud Documentation
Our colleague Guido Lena Cota was working on a project using Spring Cloud Gateway and together with his team mates did a lot of code scavenging to understand the Actuator API. After they gained enough understanding of how everything worked, they took the time to document their findings in the official documentation, helping others save time in the future.
Example #3: Fixing Formatting in AWS Documentation
While studying the AWS CodeBuild documentation on Github webhook events documentation, our colleague Manuel Vogel realized that the formatting in one of the code samples was slightly broken. He was able to fix this and improve the usability of the documentation simply by clicking the Edit this page on GitHub link in the Did this page help you? box, applying a one-line change directly in the GitHub UI and submitting the change as a pull request which was merged one day later.
Example #4: Fix A Bug In AWS SDK For Java Documentation
Similarly, our colleague Frank Wesemann came across a bug in the AWS SDK for Java 2.0 documentation, because it took him a while to realize that it was actually an issue in the documentation and not in his thinking, he submitted a pull request with a fix which was merged a couple of days later - saving future readers from going through the same cycle.
Example #5: Fix An Open Issue in Spring Boot and Gain Deeper Understanding of The Framework (And a T-Shirt on Top)
While looking for issues to work on during the annual Hacktoberfest event, our colleague Kristine Jetzke found some smaller open issues in the Spring Boot framework. One of them asked for extending the log message during application startup. While this sounded trivial at first, it took quite some time to clone the whole repo, to get everything running locally and understand how the project was structured, which classes were relevant for the change and how the testing works. Once this was done though, implementing the actual change was a piece of cake and the pull request was merged within a month and included in the next release. And it for sure feels good to see one’s own contribution every time an application starts ;-)
Example #6: Add a Feature to Starship and Learn Rust
Jan - whom we previously mentioned already - uses Starship, a CLI theme displaying all kinds of context information. In some cases it took a long time to display the command line prompt. It didn’t have an easy way to figure out which parts were responsible. Jan figured it wouldn’t be too hard to add something which gave him this information. Building it turned out to involve learning a bit of Rust... Mainly trying to understand other parts of the code, copy and paste and make it work. And getting reviews on his pull request and improving what he learned. Learning Rust in turn came in handy a short time later in his professional life.
Example #7: Add A Missing Feature to Spring Data Elasticsearch and Deliver Project on Time
While rewriting a service for one of our clients, our colleague Peer Müller wanted to introduce the Spring Data Elasticsearch library in order to reduce maintenance effort and because it fit very well into the reactive stack that was being used in the application. One of the Elasticsearch queries that had to be migrated was using the rescore functionality, which the library did not support at that time. He implemented this missing feature and after several review rounds of his pull request with the project lead, it was merged, ensuring a successful migration.
Example #8: Make Your Own Work Publicly Available
Several of our team members, among them Martin Wentzel or Martin Müller, developed tools because of their own pain points and then open sourced them. Some examples include:
- m1-terraform-provider-helper
- terraform-docker-provider (used in the official terraform tutorials)
- node-ssh-forward
- cdk-prowler
- elastic-training-repo
- our template for open-source projects
Lessons Learned
The examples above mostly show the nice and satisfying aspects of contributing to open source and, of course, not everything works out all the time. There are also a lot of examples where we spent time on something that at least felt “wasted” afterwards. And unluckily, sometimes our mistakes took not only our own time but that of others as well (sorry!). In this section, we want to share some of our learnings from those mistakes.
Example #1: Open a Bug That Is Actually Not a Bug
Our colleague John Nguyen’s first open source contribution (thanks for sharing this with a broader audience, John) was a bug report that turned out not to be a bug at all, but just a configuration error on his side.
Jan has a similar story: His first open source contribution was “a plain stupid PR” (his words) where he only later realized that he should have tested his change properly. He embarrassedly closed the PR and sent a “sorry for the noise” message. Luckily - like with most open source communities - the answer we got was super nice: No worries [...]. Thanks for the interest!”
Lesson Learned: Hard to say. On the one hand, no one wants to burden the maintainers with useless bug reports. On the other hand, sometimes you are not the only one that thinks something is a bug that actually isn’t, so that reporting it might help out someone else or make the maintainer aware that there is a general issue in understanding certain aspects. But in any case it helps to
- Be as precise as possible in your issue description. Some projects use issue templates that provide a checklist. Make sure you give the necessary details when you submit the issue. Put yourself in the shoes of the maintainer and include everything you yourself dream of when you get an issue to look at.
- Do your due diligence and make sure the issue hasn’t already been reported. Search for similar issues first. If you don’t find any, double-double-double-check that it is actually a valid issue. Don’t waste anyone’s (spare) time.
- And speaking of people spending their spare time on maintaining projects: Always be polite. Always be humble. Always be nice. And speaking of nice: Another one of our takeaways is that usually the open source community is a very welcoming place and making a mistake is usually not a problem. Especially if it is clear that you are a beginner and just started with a project.
Example #2: Pull Request Gets Rejected
Sometimes we were too eager to propose a feature or a change without checking with the maintainers if this feature was even wanted, or without discussing the overall approach beforehand and thus choosing the wrong one, which led in numerous cases to our pull requests (and hard work ;-) ) being rejected e.g. in the case of Jan, Frank or Kristine.
Lesson Learned: Create an issue before you submit something and explain what you intend to do and get feedback on your approach. Expect that even after you submit something you might have still not chosen the best way to accomplish this task and that the maintainers might ask you to make significant changes. Don’t be offended by it. And, again, do your due diligence and make yourself familiar with the project, get a feel of what acceptable pull requests look like and what conventions to follow. A lot of repos have a CONTRIBUTING.md file explaining how to contribute, might have a code of conduct to follow, some agreements to sign and might provide issues and pull request templates to help you along. See an example from AWS CDK below:
Example #3: Issues Or Pull Request Gets Ignored
Similarly, but even more frustrating to most of us: Sometimes pull requests that we spend a lot of effort on simply get ignored and remain open for years. Seemingly critical Issues receive no reaction and are never solved. Questions remain unanswered, commits remain unmerged, bugs remain unfixed. Reasons why this happens may vary.
Lessons Learned: Before submitting something, check if the project is actively maintained. If not, chances are high that your contribution will not be considered as well. Of course, you might still choose to raise issues to just share them with other users. Or raise an issue that actually addresses the maintenance questions, e.g. as seen in the question about the Future of Hystrix. If you want to submit a change and are unsure about the level of maintenance: raise an issue first, explaining your intent and only proceed after you receive a confirmation to go ahead.
Example #4: Pull Request Gets Abandoned
This is the other way around ;-) Sometimes we started working on something and later on realized we underestimated the effort or complexity or overestimated our skills and knowledge. And sometimes life just gets in the way. Kristine for example feels quite bad about starting to work on this issue several months ago and just abandoning it with a long checklist of TODO items.
Lessons Learned: Get an overall understanding of the problem and the solution before committing to implementing it. Make small commits and document your findings and status so that others can pick up where you left off if in case it is needed.
Conclusion
Contributing to open source projects can be done in a variety of ways. It can be fun and rewarding while at the same time adding value to your own projects and other people’s work. A lot of the considerations and lessons learned are not that much different from what most of us do and have learned at $WORK anyway. So anyone with time to spare and the inclination to have their work publicly seen can (but not must!) contribute to open source.
Like what you saw here? We do have open positions: send us your CV and let's meet for a virtual coffee :-)
And one last point that cannot be stressed enough: The Open Source Community is welcoming and thankful!
This article was a joint effort between Jan Katins, who, together with his co-hosts John Nguyen, Manuel Vogel, Martin Müller and Martin Wentzel, came up with the original content for the Open Friday session and Kristine Jetzke who turned the slides into text.
-
For the difference between simple and easy see Rick Hickey’s talk Simple Made Easy ↩
Top comments (0)