A Guide To Open Source: How to Empower Engineers to Open Source More Often

Engineers tend to be hardwired for knowledge sharing. Because of our Buffer culture, contributing to the open source community has never been an uphill battle. We’ve never had to “convince” anyone that this a good idea and that we should let engineers spend time on it.

So, why weren’t we doing it more?

If you take Buffer at face value, we’re practically a company built for this type of thing. We want to join the discussion.

This default to transparency is an incredible asset when it comes to open source. And as far as the challenge of getting engineers to open source more of their code, I was surprised at how simple the solution actually was. I’d love to tell you exactly what we did and to hear any of your thoughts about how you tackle open source at your company.

We Have All The Right Pieces, So Why Weren’t We Open Sourcing More?

That question is something I’ve spent the last month or so really trying to solve. At Buffer, here’s what the state of engineering looks like:

• We have a company and CEO that believe in open source and greatly value it
• Directly above our engineers, our engineering managers also value and encourage it
• We enjoy the freedom and autonomy within teams to execute on open source; and
• We have modular, tested, and useful code to share

This seems like a dream setup, right? Where is the stop energy coming from?

After digging into that question, I uncovered a few obvious answers.

If you were to sit down and ask any of us why something that was open-source worthy wasn’t open source, the answer would likely be something like:

• I wasn’t sure if I could open source that
• I wasn’t sure if it was even safe to open source
• I wasn’t clear if it was okay to spend time doing that
• I don’t know what our “process” is for open sourcing code, do we even have one?

Each one of those thoughts are equal parts valid, thoughtful, and fair. But it also reveals a feedback loop that we had inadvertently created where all sides were saying “It’s okay to open source! We should open source!” but nobody really knew how to do it.

Here’s How We Got People Confident With Open Sourcing

Looking at it from this new angle, it was apparent that we needed a source, or some type of document, that addressed all of these hesitations.

It was also imperative that it wasn’t important information that was scattered across several independent sources, which can sometimes happen with new data on remote teams. If you have to ping someone in Slack to get a link to a document in Dropbox that links to another thread in Gmail leading to a Discourse post – the information would do what any of us might do with too many directions: get a bit lost.

Thinking on this, I had a renewed thankfulness spring up when I realized that we’d recently made a dedicated space for all of our open source code already on GitHub. Putting our findings here would be perfect, as not only our code would be found on our open source page, but also a reason as to how it got there and why.

Anybody at Buffer could access it, and true to our company values, absolutely anyone else could, too.

Considering we had our obstacles identified and a perfect place to insert possible solutions, the only thing left to provide were the answers themselves.

Easy to Follow, Easy to Read, Easy to Act On

It may seem anticlimactic, but the document we created with a lot of help and input from the team, ended up being nothing more than a glorified FAQ paper. And yet, it gave us all we needed so effectively. It seemed unintuitive to really try to make it anything else.

What we didn’t want was a 10-page manual, a long list of processes to follow, or rules to commit to memory. We wanted something you could skim over in about 30 seconds and get it, with the door open if you wanted to read up a bit more on any piece of it.

Anything more would just lead to paralysis by analysis, and anything less wouldn’t cover all the edge cases.

Here it is, in its entirety:

Buffer Open Source Software (BOSS) – FAQ

Need to know how open source works at Buffer? This is the place!

1. What license do we release software under?
– We release all of our open source software under the M.I.T. license. It’s very freeing and not restrictive, literally the only “ask” it contains is that they include the license with the software.

2. What can I open source?
– We want to try and share all we can, it’s quite literally who we are as a company. The value of transparency should flow over to our codebase as much as it does into all other parts of the company. If you feel you’ve worked on something that can help others, by all means – pay it forward and share it to help others out.

One aspect to always consider is security, something we’re always cognizant of even more so since the hack. Does this code have any API keys? Is there sensitive data hardcoded in any strings? Things like this should always be the first question to ask, and if the answer is yes – abstract out the code if you can to another repo. Security comes before open sourcing our code, since it ensures our quality of life for the code and our awesome customers!

Another gotcha – if you’re open sourcing a mature repo, make sure there aren’t any sensitive commits someone could go back and view. If you aren’t sure, it’s much easier to just create a fresh repo and add the code there.

3. What should I open source?
– Even though we want to share all we can, we also want to share code that’s particularly helpful and modular. This is why we don’t flip our entire web or mobile repos to public. Would that be neat? Yea, I think so. But it’s also not the most actionable service we can provide to the community.

But, some of the hard problems we’ve solved – those are perfect. For example, on iOS there are no stock controls to display an image, support pinch to zoom, paging or have a nice black background to focus on the content. We’ve solved that problem though, and it was (and still is) a great example of what we like to open source.

4. Can I spend time on open source? Is it part of our cycles? Can I spend time contributing back to other open source projects?

– We value transparency, and open sourcing our code is part of that ethos, so it’s important to us. If you feel you’re about to work on something that’s an open source candidate, remember to code for that from the beginning. If you’re asked about any time estimates, include that time along with it.
– The free roam period of our cycles is a great spot to look at contributing back to open source projects if you’re not in a natural spot to do so.

5. How do I open source – what’s it all look like end to end?
– Double check the code and the repo fit the bill for being secure, and that it contains no sensitive data ✅
– Consult anyone else on your team if need be, i.e. “Heads up – I’m about to flip this repo to public.” ✅
– Adding a good README is key for open source, so now is a good time to add one. For a phenomenal example, check this one out.
– Make the repo public on Github ✅
– Celebrate and party that we’ve helped out the community some more and shared our knowledge! ?
– Add your open source project to our open source page, here’s some info on how to do that. ✅
– Tweet it out on @bufferdevs – and pat yourself on the back! ✅

6. Any general tips?

– It’s great to think about coding for open source from the beginning. Keeping an “open source” mindset can also lead to objectively better code, since it enforces abstraction inherently and makes you think about processes more proactively.
– //Commenting is great! #DocumentAllTheThings
– Feel free to let Jordan know you’ve open sourced something so he can tweet it out on @bufferdevs – or feel free to add it to the queue yourself! If you’re not a content contributor to that account, Jordan can add you or you can hop into admin and add yourself, either way!
– Any other questions you couldn’t quite get answered here? Feel free to tap on the shoulder of someone from your team, or ask your lead any questions. Jordan is also available to answer any questions – and the #eng-opensource channel is a great place to chat too!

Here’s a link to an image of this guide if you’re keen to grab it.

I must admit that I tried to figure out a way to tack more into the title acronym, possibly For Your Information – Buffers Open Source Software Frequently Asked Questions: In Case You Missed it. Or, FYI – BOSS FAQ: ICYMI

Rolls off the tongue, no? Regardless, the name just kind of came up during conversation and it made us laugh. So, we stuck with it.

Why Didn’t We Put Together This Document Sooner?

Every industry, regardless of the trade, will often hear about empowering developers or any employee – but what does that actually look like? What steps do you have to take? Personally that’s something I learned is easy to say in engineering, but hard to take as an abstract concept and come up with solid answers.

This whole experience made me ask myself, if I had known that simply writing up an FAQ document could help other Buffer developers get in on open source, and feel empowered to do it, wouldn’t I have dropped anything else in that moment and have written it right away? Wouldn’t I do it sooner? Of course I would. Who wouldn’t?

But, like so many things with engineering, it’s a “you learn balance by falling” type of thing. We were surrounded by good intentions and willing developers but a bit lacking in terms of how to execute.

I’m glad we’ve got something for that now, and our code continues to become more open almost weekly. We’re super excited that roughly 80 percent of our open source projects came to fruition this year (in fact most in this last quarter).

Over to You

• Any thoughts on improvements we could make to our Open source doc?
• Does your company contribute to the Open source community?

I’d love to hear from you in the comments or on Twitter I’m @JordanMorgan10.

P.S.: Want to get posts like this directly to your inbox? Sign up for the Open blog RSS here.