I Contributed to Open Source (and it was hard...)

With Hacktoberfest coming up in just over a month I thought now was a great time to share my experience contributing to my first Open Source project (that wasn't my own).

Why Open Source?

I don't want to spend too much time on this question from a social perspective because there is already a lot of writing on the value of Open Source tools within the technology community. What I do want to do though is share why I have wanted to contribute to Open Source for so long.

Just as my Honours year at university was winding down I applied for (and successfully received) a PhD scholarship, which for various reasons I ended up turning down. However, my initial desire to chase a life of academia was born out of a conversation I have replayed with a friend a few times over late nights.

He shared his passion for the academic system and particularly the PhD path. This idea that we all incrementally make progress by adapting and uplifting each others ideas and ultimately then give that knowledge back to the rest of the world to use in ways that empower and help each other at scale. While I am critical of whether the modern day university fills that romantic notion any more there was something elegant to being able to give back in some small way. That my actions would ultimately be greater than the sum of parts I had to put in to make it possible.

Open Source represents that same ideal to me. That I am able to make a series of small changes that ultimately, along with my peers, make for a better thing™ is a really rewarding and empowering idea. I think it captures the essence of what I was searching for in academia but seems to apply it in a more pragmatic and timely approach.

I lay out the above because for me contributing to Open Source is akin to volunteering. It requires my time to make something better (hopefully) and have others enjoy it. My time has inherent value and so when I chose I was ready to commit to Open Source it needed to be for a project (or projects) that I either used or wanted to support.

Getting Started

Here is the issue though, just because I use certain software doesn't mean I always know how it works, or in some cases, it just doesn't utilise the languages or skills I know. For some people this provides a fantastic place to start learning new skills or pick up a new challenge. But what if you're a relatively new coder, or at the very least, new to collaborating on Open Source projects? You, like me, probably want to tackle a language you know and hopefully a tool where the code base is at least representative of work you have done in the past.

With Hacktoberfest coming out soon I took some time out of a quiet work day to do some investigation. What repositories were out there that I knew of and thought were worth supporting? Of those which ones had languages I was comfortable with? Did those repositories have huge communities where issues were either snapped up really quickly (or the sheer volume was overwhelming)? Was there anything that looked small enough that I can conceivably grab and get a small win on in a day or so? There's a lot of things that can be a blocker to getting started that aren't just code related.

After a while I ran into the Ghost blogging platform (the very platform that powers this site). It seemed perfect, it was in a language that I was familiar with and it was a product I used. By chance 9 hours earlier a small visual defect in the Admin Panel was raised as an issue which seemed like something I could pick off.

Setting Up My Development Environment

What I have always taken for granted on my development projects has either been that they are "green-fields" (brand new) or I've worked with someone that I am inheriting the project from so there is a wealth of knowledge on how to set up and maintain those projects. Additionally as most of those have been with similar team members the patterns are the same. Despite Ghost providing robust install from source documentation it will still frustrating to get it to run locally. For brevity here was roughly the journey:

• Not wanting to run yarn side-by-side with my npm installs
• Windows being unfriendly with some Ghost related setup (like having to run Powershell in Admin mode?)
• Trying to circumvent the whole issue by running it in a Docker container.
• Realising that the Ghost install only listens on localhost and having to change default values to listen on all IP addresses so I can access it from my host machine, then worrying I will accidentally commit the file.
• Giving up and just running yarn and npm next to each other...
• Yarn commands not working unless I prepended them with yarn because npm was trying to take over!!!!

Making The Change

It is really cumbersome looking through a new code base to find where things hang together. There is a feeling of complete loss and confusion. Hacking in a fix is generally pretty easy. Is this the right place, is this where the maintainers would want me to put it? How thoroughly do I need to test the fix, it's three lines of code! What if I cause a regression? Has someone else already fixed it in the time it has taken me to track the fix down?

About 4 hours after deciding that I was now an Open Source Contributor I was feeling a little tired but glad I took the plunge, now all I had to do was get the PR up and wait...

Making the PR

Although I am starting to adopt Github for some of my public side projects I am largely familiar with Bitbucket and Azure DevOps and predominantly on single projects where merges happen internally on branches. So forking repositories and making merges from one repository to another and trying to work out if I can link issue tickets from the main repository to a sub-repository was all a little taxing. It's doable and it's not hard, and almost all of it is reversible but you still want to get it right. Having my first Open Source PR publicly rejected because I missed something silly would have been embarrassing for me. Thankfully the good folks over at Digital Ocean do have a good primer on this if you're new to the wacky world of Open Source Pull Requests.

Using my Changes

In less than 24 hours my change was approved, merged and included in a new build. The following morning I was able to update this very blog with Version 3.31.1 (for those of you playing along at home) and my glorious css selector was added to the code editor widget here in the very Admin Panel I am using now. Pretty cool!

Where To Next?

I always have a lot of side projects I am keen on and there is one I plan on starting around Hacktoberfest because it seems like a great way to get a free t-shirt and work on something that is both fun and maybe pointless! I'm definitely going to keep an eye on software I use (or think should continue to exist) and try and pick more of these smaller issues up. It was rewarding to give back to the software that I get to use for free.

With that said I do hope the Open Source maintainers try to find easier ways to get projects up and running for local development. If I could download a docker image, do some minimal set up to that and just connect to it via VSCode to do all my development work that would get me onboard so much faster. Having to stand things up and configure them for what was a three line change was definitely at some points a little frustrating. And if I don't come back and pick up anything soon it was definitely a lot of work for a small reward.

Perhaps for Hacktoberfest I will get lucky and find some other small PR's or even documentation fixes. If you're like me and looking for a place to start then I found that the "Awesome For Beginners" List was a good place to start.

With it all said and done it was great to finally break that seal of indecision and get in there and give it a go. It went better than I thought and I am now more confident to try it again in the future. Just don't take the easy tickets from me if you can help it 😉. Happy Open Sourcing!