The value of drive-through contributions

The conventional viewpoint among open-source projects is that drive-through contributors—meaning people who make one pull request, patch, or other contribution then are never seen again—are problematic. At best, one would prefer to lure the contributor back, eventually cultivating them into a regular project participant. At worst, they can be seen as a disruption, taking up developers' time for work that may, ultimately, lead nowhere. At OSCON 2016 in Austin Texas, however, Vicky "VM" Brasseur from HP Enterprise presented an alternative viewpoint. Drive-through contributors are a good sign of a healthy project, she said, and optimizing the project to meet drive-through contributors' needs benefits contributors of every stripe.

Brasseur noted at the outset that the desire to capture drive-through contributors and convert them into regulars was a good instinct, but said it was simply out-of-scope for her presentation. Instead, she wanted to explore what motivates drive-through contributors and see how projects can best make use of them. For the purposes of the talk, she explained, a "contribution" included anything that could be kept in version control, be it code, documentation, artwork, or anything else.

There are four major categories of drive-through contributor, she said: self-service contributors, work-related contributors, special-project contributors, and documentation fixers. Self-service contributors are those needing to get the project working for some other, larger purpose; perhaps they fix a bug that affects them, so they submit a patch for that fix and never return. Work-related contributors are similar, except that they are working with the open-source project at their day job, and have no other attachment to it: they will submit patches needed to get the job done, but do not get invested otherwise. Special projects include people enabling obscure hardware ports or supporting peculiar configurations; they care enough to get the project code working for that new scenario, but that is all. And documentation fixers are rather self-evident: they see a missing section or typo, send a fix, and consider the job done.

For projects, the interesting questions are why the contributor shows up at all and why they disappear. Many drive-through contributors tend to show up in the first place just to scratch their own itch (the self-service and special-projects contributor categories in particular). But there are other possibilities, she said: the contributor may have no choice but to use the project, even though they do not care for it, for instance. An example would be a developer who prefers PostgreSQL, but who is working on a MySQL project at their day job. When the job is complete, they will likely return to PostgreSQL. And, in some cases, drive-through contributors submit a patch simply because they like you: they notice something wrong and send a fix because they care about open source.

On the flip side, these contributors depart for a handful of reasons worth reflecting on, too. When the itch is scratched or the work project is finished, they may simply move on. But it is also common for contributors to start with good intentions and simply run out of time; "life happens," she reminded the audience. Drive-through contributors also sometimes move on because they find another project that suits them better. That, too, comes with the territory. Yet there are a few reasons for a drive-through contributor's departure that should worry the project: when contributors find it too difficult to work with the project, when they feel like their contribution was not appreciated, and when some project member treated them poorly.

The latter case is the "asshole problem," she said; it is a common criticism of open-source projects, but it is even more pointed when drive-through contributors are involved. Too many developers treat drive-through contributors with hostility, calling them a "waste of time" or words to that effect. These developers tend to claim that drive-through contributors are time sinks and that they are not "part of the community and never will be."

But that represents a misunderstanding, Brasseur said, of how "community" and "contributors" relate. Often, projects talk about community as the base of a pyramid, with contributors a smaller level above that and "core" developers at the top. In reality, she said, the contributor base (including drive-through contributors) is larger than the project community; it is the foundation of the project pyramid—as illustrated in the diagram to the left. "You can't build a community with no contributors—they come first."

Consequently, she said, an increasing number of drive-through contributors should be seen by the project as a positive sign. Conversely, a project with few drive-through contributions may not be as healthy as it thinks it is. Lots of drive-throughs means more people are seeing the project, more people are using the software, and that the process for making a contribution is easy and working well. Therefore, more people will make contributions (of every type) and the community can develop. Improving the number of drive-through contributions means more bugs are located and fixed, more documentation is written, test coverage is expanded, and releases can be faster. Furthermore, the project's reputation is likely to improve as well, with it being seen as friendlier and more accessible. Thus, while there are a lot of ways to measure "project health," she said, growing the number of drive-through contributions improves almost every metric.

She then turned to providing some advice on how to make drive-through contributions easier. About half of the methods revolved around documentation, she said. Better documentation cuts down on questions by providing potential contributors with the necessary information up front, and it standardizes processes across the project.

In particular, Brasseur recommended writing a "quick start" guide that offers a high-level summary of the contribution process, plus an in-depth "how to contribute" document that addresses the steps in detail: how to format patches, how to submit any contributor agreements required, how merges are approved, and so on. These documents minimize the number of "how do I start" and "what do I do next" questions that project members will have to field. She also recommended documenting the project's communication routes (i.e., who to contact on various topics) and a code of conduct. "Writing one won't kill you," she said about the latter. "It just shows people that you give a damn about them."

A few other documents worth creating include a "who's who" that explains leadership roles, subject-matter experts, and any sub-teams within the project, a "rules and processes" document, a jargon file, and a project roadmap. The "rules and processes" document should explain how someone becomes a core contributor, which can be quite inspirational for new contributors to see, as well as various bylaws and governance structures. The project roadmap helps new contributors by explaining the release schedule, the planned features, and what it will take to get a patch into a particular release.

Beyond documentation, she outlined several other methods for improving the contribution experience. Project members can mentor new contributors by doing code reviews, holding IRC "office hours" to answer questions, and by holding hackfests open to the public (perhaps even hackfests specifically geared toward new contributors). Projects can do things to improve their processes as well, she said. Suggestions include tagging "starter" bugs, providing pre-built containers or virtual-machine images of the development environment, and having a public "service level agreement" (SLA) for contributions. The SLA, she explained, means making a pledge that (for example) "we will look at each patch and respond to it within five days." That encourages newcomers by telling them that their effort will not be overlooked, and it sets expectations.

On a larger scale, she said, projects would be wise to cultivate a culture that values contributions and contributors. They can make sure that all contributions are credited in the release notes and Contributors file, they can "default to assistance" when they encounter a new contributor, and they can place a high value on documentation. "It is much easier to document as-you-go than it is to tackle a long list of documentation all at once."

Projects also need to create and enforce a "no assholes" rule, she said. "There's talk in the world about the unicorn 10X developer," she said. "But I don't care how many X's they have; if they act like an asshole they're bringing everybody down." Fortunately, she said, the majority of the time, people who treat others poorly and with hostility are not doing so intentionally—they only know that the rest of the project lets them continue acting the way they do. Most of the time, telling them why there is a problem and what they are expected to do next time is sufficient.

Finally, Brasseur advised projects to engage in outreach to contributors. They should express gratitude for contributions (including drive-through contributions), recognize each contributor, and follow up after the fact. Follow-up may include asking the contributor how their experience was, if there is anything about the process that could be improved, and (in the case of drive-through contributors) why they left. To be certain, not every drive-through contributor will—or even can—be cultivated into a regular project member. But, Brasseur said in closing, "all of the steps you take to maximize drive-through contributions also lead to a healthier project overall."

The session ended with a few questions from the audience; one person asked for examples of large projects that do a good job at the sort of documentation discussed in the talk. Brasseur replied that OpenStack does well in this regard, as do many Apache projects and the Django project. Another audience member asked how to encourage the drive-through contributors who leave for lack of time to reconsider. Brasseur echoed what someone else in the audience offered as a reply: perhaps the best thing a project can do is feel grateful that the drive-through contributor, even when busy, took some of their time to stop and make a contribution.