Run All Projects Like Open Source Projects

You can move faster when other people can contribute to your projects and unblock themselves.

Written by Xavier Shay.

I run all of my internal company projects the same way I run my open source projects.

Fundamentally this means focusing on stewardship, not ownership. Push feature requests back on to those requesting them. Don’t feel compelled to implement everything everyone asks of you. Fix the most critical bugs, but others should feel encouraged and enabled to make contributions.

There are technical ways to do this: make it dead simple for someone to grab a copy of your code and start poking around. Ideally a single script (script/dev) can get someone up and running. Provide fake data and a way to get a development server or environment running. For particularly complicated projects, document what your development process looks like. Maybe you have a staging setup that you use to test large changes? Make that explicit. Ensure any “interesting” architecture, testing, or style choices are written down in the README.

This technical bar is the price of entry, but the most powerful ways to encourage contribution are non-technical. Offer to pair with people to get them set up and developing, or to add your library to their project. Even if it’s a well-documented one-liner, sit with them and show them just how easy it is. Provide fast review on issues and pull requests. Even though you and your team will likely be contributing 95% of the code, others should feel like they could jump in if needed. This feeling is important, even if they never end up actually contributing! It gives people a sense of ownership and community around the project, which in turns encourages them to work with you and contribute rather than just throwing requirements over the wall. People are far happier and productive when they like, respect, and feel like they have control over the projects they use.

A recent example of this is the buildpack for Ruby projects in our deployment system. In our environment making sure your application is bundled with Jetty correctly, can compile assets reliably on a different system, and has all the right launch scripts is somewhat subtle. This logic was being duplicated around teams, with the same bugs cropping up and causing oncall load for the Production Experience team (we help teams get their code into production). We pulled all this logic into a common project — still “owned” by Production Experience — but made it easy to get started, run locally, and run the tests. I left a couple of “obvious” but easy to implement features out, as low hanging fruit for others who wanted to jump in. After a few weeks it has already seen commits from eight different developers. Better yet, they have even started reviewing my commits! This enables them to add the features they need, read code to solve problems, and frees me up from being involved in every line of code.

Create a path of least resistance for people to use and contribute to your project. Everyone will be happier for it.

Won’t all this overhead slow us down?

This is a common objection I hear, but in my experience what happens is the opposite. Running internal projects like open source projects enables others to unblock themselves without creating extra work. Even if you only account for the cost of a new team member getting up to speed (or your future self remembering how any of this works!), the balance still comes out positive.

The following time sinks are often associated with open source, and are nice to have, but totally not required for this to work.

  • Comprehensive documentation. If I can easily jump in and start hacking I’ll figure things out. As long as there is a good README to point me in the right direction.

  • Ceremony around releases. Just cut releases when/if people ask for them and point at source control for the changelog, though it’s easiest to have everyone work off latest head. (This works best with a culture of upgrading early and often.)

When you empower others to make changes to your projects it helps them maintain momentum and frees up your time to focus on other tasks and move faster. Xavier Shay (@xshay) | Twitter The latest Tweets from Xavier Shay (@xshay). Engineering Manager at Square. Vegan. Running is the best. San

Table Of Contents