Skip to content

Instantly share code, notes, and snippets.

@mbbroberg

mbbroberg/contributions.md

Forked from FlorianHeigl/contributions.md
Last active May 16, 2016 19:43
Show Gist options
  • Save mbbroberg/83066b78e29c1f947d65171d832797c4 to your computer and use it in GitHub Desktop.
Save mbbroberg/83066b78e29c1f947d65171d832797c4 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
contributions.md

about accepting contributions on open source projects. This guide is designed as a TL;DR broken out into three sections:

  1. The issue
  2. The reason it happens
  3. How to improve

I hope this helps you reflect on your contribution processes and improves your community (and its code).

"unfit" patches

  • crappy code
  • stuff you just rewrite instead of signing it off
  • missing pieces (i.e. no example in/output)
  • code where someone got excited and it grew and grew and now it's 50 lines for the 3 lines it should have been.

happens because:

  • you don't have a style guide
  • you have high (and possibly unreasonable) requirements
  • people don't read (and that's yoru fault. Some of us are just very slow readers and need a tl;dr)
  • people are trying to build code the way THEY like it

how to manage:

  • try to work your real quality goals into the style guide (not just indentation but when it's OK to break out to a subfunction. if you try to be consistent about something, it should be documented somewhere)
  • can you dedicate someone to help contributors? Having a resource ready to clean up stuff so this becomes a fast routine instead of a awkward thing you do in(stead of) pastime
  • be darn hard about what your code looks like and make it visible that it'll not be OK if it's not matching to what the project wants

"blob" drops

  • need days to integrate
  • might still influence other parts
  • might take longer than anyone's normal attention span to review
  • means other features or issues need to be pushed back for the contrib

happens because:

  • it's too hard to contribute for them!
  • standard functionality too trivial
  • complex features that some need but never get attention foster big "drops"
  • little requests are ignored a few times, so they stop sending little contributions
  • other case if they i.e. add support for a new hardware which is not yet public
  • they hack until they're sure it "could be OK." This means, basically, they keep adding stuff outside their main goal just to raise chance it'll get accepted. or they just go crazy about it and keep adding anything they can think of because they're proud

manage this by:

  • have guideline for larger contributions or such that need time to cook up (open issues & PR early)
  • have a public CI as gatekeeper (people less afraid of that, and they can make it "pluggable" independently, so effort scales better)
  • make sure they understand it's totally normal if they break their own branch at first
  • let others do this support (thus, have everything public, so they can ask and work well without being a core dev)
  • have a contact for them, if they got a 20K line commit for you they should get in touch there. two people can sort out a lot of issues by a single irc chat.

contribs that subvert the project goals

you got a large contribution that does something that, well, just doesn't have anything to do or in common with all the other parts of your software you love.

happens because:

  • the user loves your software!
  • he ended up using it as a hammer for EVERY nail
  • he's got other problems to tackle but doesn't want to have yet another interface to do it.
  • you might have code still around that also went to a different direction. you don't think about it anymore, and you might never have liked it because it didn't play out nicely. but others still see it and might just be riding that elephant in your room.

manage this by:

  • make sure your software has a well-defined scope and architecture. if you make it sound almighty, you can't complain about random additions :)
  • be interoperable! your software should fit under a common umbrella (i.e. having other tools that directly integrate, like an Ansible module) and is able to be an umbrella without needing to extend it internally (so yes, hooks/plugins, and please expose the full internal state to them)
  • decide, consistently, if you should remove non-core code you hate
  • then do it

NOTE: but while deciding, make sure you honestly evaluate the potential of the feature. you never know, someone else might contribute a nice idea that makes it work better. if deleting that code removes a whole class of functionality from your software, it's a bit of a weird thing to do. if it's unmaintainable for you because i.e. it works with some standard you don't normally work with, state that somewhere in your project. no one thinks you can know everything. if they know it's a maintenance issue, maybe they can do something about it.

For example, large corporations with 100s of storage arrays will be better at testing against them than someone writing a small plugin in their software to support them.

Summed up: let people know what the core teams' strengths are. This gives you a strong position to demand they keep technical ownership of the contribution instead of offloading decades of ongoing maintenance to you

undefined random features get added randomly:

  • you randomly get outside of tree contributions for insane features
  • major contributions to your project happen but are later forgotten
  • your project is called Xen

happens because:

  • your software is alive and used i.e. as a base for research
  • your interfaces are apparently well-designed and it's possible to build castle upon skies using your software. this is awesome.
  • your development process and project leadership are horrible.
  • people who start coding major additions to your software are NOT aware who to get in touch with and when to do it.

how to fix it:

  • define a community manager with decision power (Xen did that, fixed their issues)
  • Provide ways to communicate with the community, both real-time (like Gitter, IRC) and asychronous (like GitHub Issues)

constant flow of questions and complaints

happens because:

  • you're having fake FAQs

  • most projects separate developers and "contributors"

  • this, in essence, says that people maintaining your wiki, faq or spending many hours answering support questions are somehow less important.

  • if you feel overwhelmed integrating contributions or doing support, you need to find ways to invite more people to the project.

  • testers and doc writers are your best line of defence against fragile contributions.

  • like devs, they can work on multiple projects and improve their output quality with the practice.

how manage this:

  • don't separate developers and contributors. name teams, or name everyone.
  • take help to stop having TODOS in your documentation.
  • take help to stop inadvertedly breaking edge case functionality.
  • stop having to worry any of this - instead say thanks to someone who keeps their eys on that.
  • your FAQ should not consist of the question a devs considers 'worthy', and people shouldn't have to beg for something to be added to it. let someone review your support channels for common issues and write the FAQ based on that.
  • make testers your peers when the roadmap is decided on. (if they spot a weird issue, it will fall on your head later anyway, so don't be an idiot!)
  • listen to doc writers. (i.e. a shitty cli can ruin your project worse than some other flaws)

failed / unacceptable contributions

happens because:

  • most people who aren't the project inventor will deliver worse code
  • having no requirements will not let them know it's too bad
  • often they'll also just not be devs but experts in another area
  • contributions can also just be so bad it's faster to rewrite them

how to manage:

  • make QA happen external of the dev team
  • have strict style guide
  • let QA people fight that battle, let pull requests belong to them
  • give them authority to rewrite and commit what they liked. you can fix it anyway, but don't stop them after they cleaned stuff up.
  • make clear which areas are NOT OK for any "non-core-dev" contributions. i.e.: Crypto support. The Debian issues came from letting a "normal" level person work on code that needed extreme skills.

Remember: Normally you need to answer every pull request you get

  • how does it scale?
  • did you consider letting more people do this?
  • describe a way to ask for help if one just doesn't figure out how to get it right?
  • describe a list of criteria that will never be accepted?
  • also, this will be needed, make clear when someone stepped over any line. kick them out and let them know. (but please, don't take yourself too seriously: if your software is constantly causing data loss, don't feel insulted if someone jokes about it)

More tactics to keep in mind

Require Ownerships:

  • you should have a staging area for contributions. they can go there but they can't leave without a maintainer.
  • pull out-of-tree contributuions to it. DO THAT.
  • run all your tests against them so it'll be visible publicly when they break due to not being rebased.
  • have a community manager who can reach out to the people behind the software or whoever took over the next internship at their research lab.
  • the general goal should be to make them work with and on your base.

that way you can make sure at least basic project management or what EVER you like in your project can apply to their code, too.

Great examples:

  • ceph blueprints:

forces "requester" to outline what they really want allows to keep track of far-fetched 'killer features' noone can build now. channels interaction: anyone wanting to add a feature like that can be pointed at the community approved design allows testers / users / devs for a feature to materialize and meet before implementation even starts. they'll be ready to support whoever tackles the hard bits.

  • bacula vote:

anyone who has a good idea of a missing feature can spec it out. they themselves have no extra influence on when if / it'll happen.

instead, anyone can pick up on it if they have the resources. if they want to change the implementation away from the spec, they can do that in discussion with the people who raised they hand to be interested in that feature. avoids getting 3 different conflicting implementations of a thing over time.

the scheme behind this is:

  • use your community ressources to spec out features
  • do not lose those specs, requirements engineering is expensive.
  • you are getting valuable contributions there, don't think this is worthless
  • if you ignore this stuff, you get forked badly

you'll have to write the same code as they wanted on average a year after the fork because your community will most definitely demand it once it's in the fork. (Hello SambaTNG/Samba, Bacula/Bareos, Nagios/Naemon...)

we have a large tooling problem there, make sure those things don't get opened as github issues but as something else. otherwise you end up in a trap where you need to close them to maintain project visibility.

Finale and thank yous

HERE:

  • Inspired by Matt
  • Written by Flo
  • Reviewed by Marco
  • The Xen joke was further smiled at by Cecile

Solid examples:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment