Contributing to Open-Source
Over the last six months here at CustomInk we’ve been building an internal Content Management System (CMS) named Inkpress to help various company stakeholders design and publish a wide array of landing pages that drive overall business objectives. Inkpress makes heavy use of AlchemyCMS - an open-source Rails engine - to help power the user interface and manage much of the back-end page template and element data. It’s a fantastic piece of software, but there was one small issue: we rely heavily on using Sass frameworks that are compatible with SassC and hence SassC::Rails. Unfortunately, because AlchemyCMS was using the SassyButtons and Compass libraries, we were unable to make use of the super fast SassC pre-processor to make Inkpress as quick and snappy as the rest of the site. As a result, my colleague Ken and I decided to reach out to the project’s primary maintainer to get his thoughts on making some contributions that we felt would improve not only his software, but also improve ours in the process. He agreed, and we decided to use this year’s Inkovate as an opportunity to take the initial leap.
Why Open Source is Important
Before jumping into my specific experience contributing to AlchemyCMS, it makes sense to discuss a little bit about why we, at CustomInk, believe that contributing to open source is important. Here are just a few reasons:
1. It Builds Community
At CustomInk we put a maaaaajor emphasis on building communities. So much of the work we do as a company orbits around the idea of creating bonds, building bridges, and uniting people around the things they care about. Heck, even our homepage proclaims that “We Believe T-shirts Unite!” It’s right there, next to our primary call-to-action. This core business philosophy also happens to line up perfectly with the open-source software model’s very core. The idea (and you can find much of this and more from the Open-source software wikipedia page) is that “collaborative development from multiple independent sources generates an increasingly more diverse scope of design perspective than any one company is capable of developing and sustaining long term.” In other words, community-driven projects are often more useful to more people in more ways for longer amounts of time than those developed by individual entities. As believers in the power of community, it only makes sense that we at CustomInk stay involved in contributing to these types of open-source projects.
2. It's great practice!
Taking some time to redirect your attention away from your day-to-day projects to take on an open-source contribution really helps to hone your skill set. In my case, it forced me to crack open a library we use for one of our company apps and deeply explore its unfamiliar insides. In doing so, I gained even more perspective into the way the library is structured, how the code flows, and what other abilities or limitations might exist. Developing that amount of familiarity with a library we rely on daily has been extremely rewarding and given me even more insight into the context of the entire app-to-engine relationship between Inkpress and AlchemyCMS.
3. It’s incredibly rewarding
This is likely one of the main reasons any of us decided to become software developers in the first place, but it holds particularly true when working in an open-source environment. We all know it’s rewarding to tap on a few keys, click a button, and see our work come to to life and make business impacts, but it’s even more rewarding when the problems we solve and the impacts we make reverberate beyond our immediate environment and extend into the community at large. I may have no idea who else out there is using the AlchemyCMS library, but knowing that the hard work I put into improving its speed also means improving the speed of all those developers’ apps too, really enhances the reward.
The Work
I really want to focus this post more on what I learned as opposed to what Ken and I actually did, but I also feel it makes sense to provide at the very least a basic context of the work involved, so here’s a brief rundown:
As I mentioned above, the AlchemyCMS engine was depending on two Sass libraries that were prohibitive to moving Inkpress off of the Sass::Rails pre-processor to its new and faster equivalent, SassC::Rails. Our contribution involved removing those two dependencies and rewriting the css with Sass mixins to replace the styles that they provided originally. We ended up using Bourbon for a chunk of this. Then we created a helper file required from AlchemyCMS’s engine.rb that would check for either a sass-rails or sassc-rails pre-processor in the parent app and alert its developer in the event it didn’t find one, thus allowing the flexibility for the developer to choose between either Sass or SassC in the main application. Feel free to check out the initial issue we opened to the maintainers, as well as the resulting PR, which was ultimately merged into the master codebase.
Ken and I working on our AlchemyCMS contribution during Inkovate:
Impressions from Contributing
1. Getting started is hard, but totally worth it.
It’s sometimes difficult to know how and where to start when considering contributing to open-source projects. As an early-career developer myself I’ve heard all kinds of advice on this topic, from tracking down and correcting typos in documentation to suggesting and implementing new features. My personal belief is that it doesn’t make sense to contribute to open-source just for the sake of contributing, but rather that it should be meaningful to you and purpose-driven. Is there a library you use regularly that could use an improvement? Is there an issue that’s important to you that needs open-source support? Maybe you see a problem that needs a solution and you start your own open-source project from scratch! Contributing in a meaningful way to a project that matters to you is the key to getting involved in the open-source world.
2. There’s more reward in familiarity.
Similar to the above, I found this PR to the AlchemyCMS project particularly rewarding because it had an effect on an app that I work on regularly, and will improve the quality of our project here at CustomInk. Having some sort of personal familiarity with the problems that your contribution solves can really help bring that extra motivation and result to your work.
3. Grab a buddy.
Having a partner in crime when you’re contributing to an open-source project really goes a long way. We’ve all heard about the benefits of pair programming, and carrying those same benefits to an open-source contribution can not only enhance the quality of your output, but it drives the project forward faster and enhances the community feeling that’s at the heart of open-source in the first place. I was fortunate enough to team up with my colleague Ken, who was always available to correspond with the maintainers, contribute some code of his own to push the project forward, or just offer an extra set of eyes and new approach to our work when necessary. Teamwork is at the heart of what open-source software is all about, anyway. Why not practice the same when contributing?
4. Respect goes a long way.
Don’t let your ego get the best of you. Remember that the project’s maintainers have their own vision for the project and that your contribution is a small part of that vision. Your code may be the cleanest most perfect code ever written (by decree of the code gods), but if it doesn’t fit the vision for the project, it likely won’t get accepted. Make sure you respect the maintainers’ guidance and feedback. You’re doing them a favor by contributing some code, but they have the most knowledge of the code base and should be the project leads. Ultimately you need them to green-light your work if it’s ever going to get accepted, so be respectful of that and the whole experience will be much more pleasant.
We did our best with our issue and PR to explain what we were doing as we did it, provide screenshots and/or animated gifs explaining what we were seeing or changing, and asked as many questions as we could of the maintainers to make sure that the work we were doing fit within the framework of the project and was the most logical and practical approach in their minds. Having a good rapport with the maintainers isn’t just common courtesy, it’s critical to the success of your work and builds trust for the future if you plan to continue contributing going forward.