Managing expectations with a contributions and credit policy

Maintainers of open-source projects sometimes have disagreements with contributors over how contributions are reviewed, modified, merged, and credited. A written policy describing how contributions are handled can help maintainers set reasonable expectations for potential contributors. In turn, that can make the maintainer's job easier because it can help reduce a source of friction in the project. A guide to help create this kind of policy for a project has recently been developed.

People sometimes have rather different expectations about how open-source projects function with regard to contributions. For example, a recent discussion about how to credit a Linux kernel patch that had two authors attracted more than 600 comments, covering a wide range of opinions from "the original author should have sole credit" to "the original author should get no credit at all". Another kind of disagreement is over which types of contributions are welcome: some projects don't want external contributions, or any new features, but contributors keep sending them anyway.

In the absence of a written policy, contributors will make assumptions about the way a project operates—and may start an argument if they don't get the expected response. A written policy describing how contributions are processed and credited can prevent conflicts from even starting. To help maintainers create their own policies, I co-authored a credits and contribution policy development guide with Maria Matějka, Martin Winter, Marcos Sanz, and other members of the RIPE Open Source Working Group.

Coverage

A contributions and credit policy is most useful when it focuses on areas where maintainers and contributors frequently have different, incompatible expectations, such as: what contributions are welcome, how reviews and changes will be handled, and how credit will be assigned. A policy can also include step-by-step instructions for maintainers and contributors on how to handle complicated situations, such as when a contributor won't make requested changes.

A policy can and should cover all kinds of contributions. Melissa Mendonça, a maintainer for NumPy, SciPy, and napari, said: "Often, things like docs, community, design work are not credited as contributions in the usual sense (i.e., don't give you green squares on GitHub)." A policy can help surface these contributions and create a standard process for acknowledging them.

A policy can help resolve three common dilemmas: assigning credit for multiple direct contributors, revising contributions, and attracting the right contributions.

Deciding on who deserves credit for a work is a difficult and unsolved philosophical question. Practically speaking, people assign credit for many reasons, such as rewarding people for contributing, establishing ownership of intellectual property, or tracking down the source of bugs or backdoors.

As the authors of the policy development guide, we took a practical approach to this question with our own contributions and credit policy. We asked ourselves what kind of behaviors we wanted to encourage in our project, and then assigned credit in ways that make those outcomes more likely. Since we want to attract new contributors, we give primary author credit to the new contributor even if a maintainer had to completely rewrite the contribution. Other projects can make similarly pragmatic decisions without solving the general problem of who gets credit.

Sometimes people will try to take advantage of a formal credit policy. Mendonça says that credit for open-source work is "always a system that you can game (for example, making just enough contributions to get a certain credit/position and then moving on)". However, she says that she is "willing to err on the side of giving credit", and take corrective action afterward. Any policy can have an explicit exception for the maintainer to take whatever action they think necessary.

Multi-contributor credit

Some policies for assigning credit are easy to implement, such as the current de facto policy for many projects: "whoever merges the code decides who gets credit". However, for more complex credit policies, some difficult situations quickly arise. Matějka, team leader for the BIRD routing daemon (and a co-author of the policy guide) said:

We sometimes get contributions with good ideas and poor quality. It's always a discussion how much the specific patch is more an idea (to be thanked for in the commit message) or a patch (where we keep the author but add a note that it was updated by the committer).

Many contributions need some revision before they can be merged into the main project. This can go wrong in many ways: maybe no one has time to review, contributors don't respond to requests, or the contribution no longer merges by the time it is approved. A policy can help with these situations in two ways: it can give the maintainer a playbook for how to handle difficult situations (e.g., after two weeks of no response, make the edits and merge the contribution), and it can give contributors guidelines for when to ping the maintainers (e.g., after two weeks of no response, email the mailing list again).

Attracting the right contributions

Many people assume that "open source" means "open to outside contributions and willing to mentor new contributors". In reality, some projects don't want new contributors or features, others will accept outside contributions but only after they have been totally rewritten, and only some maintainers have the time and interest to mentor new contributors. An explicit policy about what contributions are desired helps maintainers avoid conflict from would-be contributors. It also helps both potential contributors and potential users decide whether they want to depend on a project with that particular contribution policy.

One of my early open-source contributions was guided by a contributions policy of sorts. The xjack screensaver prints "All work and no play makes Jack a dull boy" over and over, with a variety of mistakes and typos, inspired by a scene in The Shining. A comment in the source code tells would-be contributors not to bother sending in a patch to change the words it prints. However, while I was doing exactly that, by changing it to print "All work and no play makes Val a dull girl", I found a bug in the code that generated typos. I sent in a patch to fix that bug, which was merged (without credit).

Policy resources

The credits and contribution policy development guide includes several variations on each section of the policy, as well as a list of policies in use by open-source projects. We request (but do not require) giving the authors credit on any derivative work. The policy guide has its own contributions and credit policy and new contributors are welcome. Currently we are especially interested in additional examples of choices for each section of the policy, as well as links to existing policies.