My favorite part about our open source project, PencilBlue, is that I get to interact with people from all over the world. When we first started, there were just two of us, but as the months progressed we saw our contributors begin to grow. It got me thinking about what it takes to be a good maintainer and how my team will make sure the project continues to run smoothly for years to come.
How many people across the world contribute to open source software? If GitHub's user base is any indication, the open source community is more than 8.5 million. That's a massive number of people that have the capacity and desire to contribute. These numbers don't even take into consideration those who clone or download distributions anonymously. Now that we know how many people we can potentially engage, how do we get them interested in our projects?
Managing an open source project comes down to three things:
Your project has to have a vision. I asked a few people in the audience at the NC State FOSS Fair: "How did you decide to start or contribute to an open source project?" All the answers were the same: "I got bored and wanted to solve a problem." The problem you are trying to solve is typically a problem shared by others. People often contribute to projects that are solving problems they are in the middle of trying to solve themselves. People who use the software or are considering contributing to the software will want to make sure that your goals align with theirs, not just that your software accomplishes their immediate needs. It's easy to make this apparent by simply fleshing out your vision in the README. It is perfectly OK to say, "I'm only 20% of the way there and it's rough, but here is what it is going to do." That goes along way.
It isn't enough to just spell out your vision. Invoke some confidence in your potential following by regularly sitting down and talking about where you want to be in the next couple of months, no more, maybe less. If you have a road map in place, it's easy to track and show progress.
Build a roadmap
Last year, we created a basic roadmap of how the last quarter of 2014 would play out. It worked well because we were asked fewer times when specific features were coming down the pipe. However, we did set some specific target dates on our road map. This became a bit of a problem when the amount of user feedback caused us to reprioritize. The long roadmap forced us to be more waterfall than agile, and while I won't dive into that debate, I will say that relative timelines tend to work better for us. For example, saying that a Media Service refactor was going to be completed in December rather than the second week in December would have been a better plan.
Get user feedback
Deciding the future of the project is the hard part. In the beginning, you only have your ideas to go on. The more contributors and/or users you have, the more imperative it is to find the vision that is best for the project and not for you personally. After all, your project must satisfy the needs of its users, not just you. This was another lesson learned by us a few months after launch. We provided what we thought was a full-featured CMS, but the user feedback was, "Hey, it would be cool if..." That feedback is amazing because it means people are actually using what you are building, or at least trying it. It may collide with your vision, but if you see it more than once, don't ignore it. The customer is always right, and you should pivot to align with what people are asking for to ensure everyone is in sync with where you are going.
Keeping your contributors within the bounds of the vision isn't always easy. You sometimes get pull requests that drastically differ from the style of the maintainers. In order to reduce this as much as possible it is critical to put in place a process for pull requests, asking questions, reinforcing design patterns, etc. Process is boring—and it's even more boring to have to spell it out for everyone—but it is the necessary evil that keeps your code maintainable.
How many times a week do you commit straight to the master instead of a feature branch? I'll be the first to admit I'm guilty of doing it at least a couple of times a week. Typically, not on the platform core, but with some of the plugins it happens.
This is a big no-no, but nonetheless we have all been or know of somebody who is that rogue coder. They are amazing at knocking things out, but they often do it at a cost to the rest of the team. The solution is to put in place a set of standards that enforce accountability from each contributor and/or user. Here are a few of the little things that we do to help alleviate rogue coder syndrome:
- Create a branch for each issue or feature you create
- Each branch name contains the issue number
- Ensure all unit tests are ran against your branch plus the merge with master
- Try not to merge your own pull request. Small teams can take a pass if there is sufficient test coverage in place.
- Let your pull requests be a learning experience. Call out why you did things a certain way. Despite what others think, three lines of inline comments is not a bad thing. It means you did something complex and can avoid a "what could I have possibly been thinking?" moment in the future.
These little things provide the needed accountability among contributors to keep everybody in sync and aligned with the project's vision.
Assume you are deciding between two similar projects. How do you choose which project to invest your time in? This is a constant battle I face when evaluating other libraries to include in PencilBlue. I look for the obvious, but with so many libraries accomplishing the same end result, there needs to a differentiator. To be honest, it comes down to perception. Your website, documentation, and your README all give first impressions. Make it count.
As a developer, I often overlook the importance of the visuals. I like to think the quality of my code speaks for itself, but with 300k lines, how do you convince somebody to sample even a single line? The fact is that people contributing over and over keep the pulse of your project at a steady rate. The steadier the pulse, the greater the chance you have at longevity.
Each maintainer needs to embrace the mantra: Accountability through transparency.
Open source projects get a lot of benefits from up and coming companies. Most of them provide tooling to help better your project in some way.
- Travis CI: provides continuous integration
- Coveralls: provides code coverage
- Code Climate: provides code analysis
- David: provides dependency analysis
Each of them provide some level of their services for free to open source projects. They also embrace the need for transparency by providing badges. Use these badges as a way to hold yourself accountable for the quality of your project. It is a simple addition that will give others confidence in your code's ability to solve their problems. People will respond well to that and rally to help accomplish a common goal.
I once read a blog post that mentioned that we can all individually write our own lightweight GTK mp3 player, or we can all come together to write one that the next generation will still be using after we retire. If you can show people where you are going, show them how to participate, and show them that you are capable, you will leverage the collective minds of others to the benefit for all.
This article is part of the The Open CMS column coordinated by Robin Muilwijk. Share your stories about working with open source content management systems (CMS) and platforms like Drupal, Joomla, Plone, WordPress, and more.