Lessons Learned Building Open Source Software

Having spent a significant amount of time conceptualizing and growing Vagrant into a decently successful open source project, I’ve come away learning quite a bit. I haven’t seen many blog posts about open source maintainers commenting on their lessons learned, so I’d like to share them here. These are not only engineering lessons, but lessons involving being an open source maintainer, promoting your project, etc.

Open Source Lessons

These are lessons that are generally applicable to open source projects.

Be friendly. This is the most important thing. You’re going to get bad ideas sent to you, people are going to get angry when something doesn’t work despite you providing your project for free, and you’re going to get terrible pull requests. Just remember that despite all this: these people are using your project, so be respectful, even if they may not be. I’ve only had one issue where I was starting to become clearly agitated, but I’m pretty proud to say that despite all that I think I remained friendly. It is important to remain friendly because as long as you are friendly you are approachable, and open source simply doesn’t work if people can’t approach you for help or contributions.

Don’t have crazy rules for contributions. Don’t worry about style, whitespace, proper indentation, etc. Unless your project is huge, complex rules for contributing only serves to hinder those people who want to contribute. Style, indentation, etc. is very quick to hand-fix. You should instead be grateful and accepting of the changes which are actually coming in, rather than any superficial attributes of it. So how do you contribute to Vagrant? Just fork the code, make your change, and pull request. I don’t care about style, tests, etc. I’m just happy to see contributions.

Documentation is key. I can’t show evidence for this, but I’m not exaggerating when I say that 100% of the first users of Vagrant who talked to me said they did so because it was so well documented. And at conferences I’ve heard more of the same. Another important thing is that writing documentation is probably the most boring thing in the world. If you put it off until the end and write in all in one go you risk becoming horribly depressed. So just slowly build up the documentation. Also, make your documentation forkable for easy contributions.

Have a clear method of communication. IRC, mailing lists, forums. It doesn’t matter what it is, but you need to have a clear way for users to get support or voice their opinions in a place that they can expect a response reasonably quickly (within 48 hours would be nice). For Vagrant, I’ve always had an IRC channel and mailing list. This has worked well. And if your users interface with you more, they gain a stronger trust for the project.

You don’t know everything. At some point, inevitably, you’ll get a feature request where you’ll say “this is useless” to yourself. The major responsibility of the project maintainer is to guide the vision of the project, not to micromanage specific features. Does the feature fit in with the vision? Is it useful for at least a couple people, even if it isn’t for yourself? Merge it. Guide the vision, be open minded, your users know what they want to see more than you do. But you know whether it fits in with the overall goal of the project better than anyone.

Marketing Lessons

So how do you get people to use your project? Here are some things I’ve learned in this space.

Hacker News. The hacker news community likes trying new things, and there are a lot of developers on there (hackers, if you would). So submit your project there, and comment in the thread saying you’re ready to answer any questions. Be friendly, because you will be criticized! Also, just some good tips: avoid submitting news when something crazy happens, submit around 1030 AM GMT-8 which is when HN is most active, don’t link your HN entry directly because upvotes won’t count, don’t try to game the system with fake accounts because you’ll get caught. When Vagrant was first released, it was #1 on Hacker News for most of the day. I received 11,000 unique page views that day (although some of that was from Reddit as well).

Reach out to popular niche blogs. In every community, especially in the Ruby community, there are niche blogs that are popular and like to report on cool projects in a specific language or field. Find these blogs, reach out to them, and get them to write about your project. This will result in two things: If they write about it, your project not only gets more eyeballs to look at it but your idea is better validated! This is the best way to get your early adopters.

Speak at meetups (before conferences). Find local meetups that would find your project interesting, and speak there. Practice speaking if you’re new to it. Don’t give a tutorial on your project, instead sell the crowd on the vision of the project, since they’re probably smart enough to do the tutorial you have with your amazing documentation (right?!). If you’re new to speaking, do not try to speak at conferences right away, because you will be bad, people will remember, and it will be that much harder for you to to ever speak again. Also, meetups give you a place to hone your vision and get important feedback from real people.

Speak at conferences. Start with regional conferences. Next, speak at regional conferences. These conferences are generally smaller but filled with good content, and people will be more forgiving if your talk doesn’t go so well. Also, the bigger conferences are unlikely to accept a talk about a project that is brand new. Now, you’re going to be in front of around 100 to 200 people and have 40 minutes. Also, you’re going to be recorded, so make sure you’re well prepared. Deliver your vision, smile, and take note of the feedback you receive. Use this to further hone your idea and stabilize your project.

Speak at big conferences. Now, I’m talking about conferences like VelocityConf or QCon. These guys will get you in front of a huge crowd of people (500+), and the audience will be extremely intelligent. Give a deeply technical talk that will challenge these folks, and again, sell your vision. Also, if your project is still relatively new, you should have examples of it being used successfully in the wild by people other than you in order to validate the whole thing. These big conferences attract generally important attendees (CIOs, VPs of Engineering, etc.) who will have a big say in getting your project in use at their big companies!

Engineering Lessons

Here are the handful of things I’ve learned about the programming side of things:

Test. I don’t think this has to be said, but since it is so important, I will include it. Tests are not something you can just bolt on to a project later. You must test early and test often. Also, don’t forget integration tests. I added integration tests to Vagrant much later, and they are by far the most valuable tests prior to release. Unit tests will catch my basic errors quickly, but integration tests will find major issues prior to a release.

Support Windows ASAP. Vagrant began supporting Windows pretty early, with John Bender doing much of the initial work. Despite Vagrant not being very feature-rich at the time, it was an absolute nightmare, since many of our dependencies didn’t work on Windows, and because there were many places in the code which expected Linux or simply called methods that didn’t work on Windows. I couldn’t imagine trying to bolt on Windows support later in the product cycle, since it can possibly require huge overhauls in your code base. Additionally, there are a significant number of Windows developers who want to use Linux-style tools. Instead of responding “Why don’t you switch to Linux?” I think its important to accommodate.

Avoid FFI. This is more of a Ruby thing. The Ruby FFI library is just not good for anything more than the simplest C libraries. I spent over 18 months working heavily with FFI. I’d even venture to guess I was one of the heaviest users of FFI. The issue is that the FFI library would routinely update and break, even in patch releases. More than a handful of times I awoke to find that Vagrant simply no longer worked on Windows due to FFI compilation issues, due to a patch release of FFI. Additionally, I found it extremely difficult to work with callbacks and dealing with memory management with FFI. Vagrant was one big memory leak until version 0.9. In the end, I ditched FFI until a better library exists, and now support C extensions again.

Become friends with the maintainers of your dependencies. Any heavy user of a library will find a bug in that library. Throughout the life of Vagrant, I’ve found a bug in every dependency. At this point, I’m reasonably good friends with the maintainers of all my dependencies, so I’m able to quickly ask “is this your bug? how long until its fixed? can you release a fix?” The worst possible output is that there is a bug in a dependency and the maintainer either won’t fix it or won’t push a release containing the fix.

In the end, I still have a lot to learn, but hopefully these tidbits will help some people out there when working on open source.