Open source is beautiful. It let’s you share your findings and learnings about software you love with a large community. I call people that contribute to open source “open sorcerers”. There are so many projects out there, ready to be deployed, completely open and for free. Signal and Threema, two secure messenger platforms, WordPress, the CMS I and many more are using for blogs like this one and even Moodle an e-learning solution that led me through my bachelor’s degree, are just examples of open source projects.
Motivation
While working on my Discord bot project, I added a third party dependency for logging, called tinylog. My intentions with logging were to visualize them in a frontend so that when a user reports a bug I am able to track the error. Tinylog has many options for customization with file writers. At that point, I struggled with the visualization bit, because the logs weren’t accessible and had to be parsed. That’s when the idea for a json file writer came, since json is natively parsable in Javascript.
Today I want to provide an insight on the process, my learnings and experiences that I made.
Where to begin?
The first thing I did was to open an issue in the tinylog repository. I called it something like “add json writer” and added a description and my motivation, similar to how I just did in this post. Another proposal was a possible “goal” on how I thought the output of the request could look like. The author of tinylog quickly approved the issue and put a “help welcome” tag on it. Hmm, seems like it’s not gonna happen soon. I was hoping someone else to take it on, but that didn’t happen. So I thought about doing it myself, but I had no clue where to start.
Luckily, in this case, tinylog provided a guide on how to write custom writers. “This is a good start”, I thought and took a look at the guide while comparing it to already implemented writers. That’s when I learned more about abstractions, interfaces and loosely coupled components in practice. The steps in the guide seemed absolutely plausible and I was pushed to do it.
The first changes
On an evening, I collected some courage and was about to begin. A very important first thing to do is to hold the goal before your eyes. What am I trying to achieve? How am I going to solve this?
Then I just started. Copy the existing file writer, and do some changes to render a json. It did not take long, until I encountered some challenges. The file writer supported an appending mode, which I wanted to take on, too. How am I supposed to append json objects correctly? I had no clue, so I quit my work and put all my efforts into the issue.
The author replied back kindly with some of his thoughts and proposed some advices. “Wow, that makes totally sense, thank you!”, I thought. With new power and advices from others, I continued working on that beast.
Pull request
I opened a pull request to continue further work in there, as the author also seemed to help me. We discussed, reviewed, communicated a lot, an even opened other issues and pull requests along the way. He gave me valuable input and critical feedback, which I’m very thankful for.
More and more, the json writer used features of the library and thus fitted into the ecosystem. The author even made some large changes himself, which he wanted me to review. I felt honored and took on the task. After some manual testing of edge cases, writing more unit tests and optimizing some code, it was a only a short time for the pull request to be merged. Phew, that’s it.
The feature was to be released in v2.4 and at the time, it was at v2.2 so there was some time. After some weeks, v2.4M1 was released, including the json writer.
Conclusion
In this post, I describe how I encountered a problem and came up with a solution to this problem. Luckily, that problem was in context of an open source library, which kindly accepts contributions.
I thought about ways to solve the problem and tried many attempts. With communication and critical reviews as tools, the author of the library and I assisted each other. I learned a lot on the way, including communicating over open source, solving problems together and some skills regarding the topic itself.
In the end the changes were approved and merged, until they were released in v2.4.
How about you?
Do you use open source libraries in your projects? Have you ever encountered a problem or a missing feature in them? Then you should not hesitate and start contributing. Even the tiniest issue in which you ask some questions count as contribution. Imagine others having the same questions that eventually get answered in your issue. Isn’t that amazing?
The open source community is often very welcoming and help is always appreciated. Often, there are contribution guidelines that provide to you a helping hand. You should check them out, as they clarify formalities to be considered. Also, you don’t need to know the library perfectly, but that really depends on the issue.
It’s OK to ask questions and it’s OK to ask for clarification. Even open sorcerers are humans and everyone begins at some point, right?
