@nayafia

Designing Useful Contributing Guides

@nayafia for OSSAT

@nayafia

Contributing guides tell people how to contribute to your project

@nayafia

GitHub has recognized CONTRIBUTING.md as a standard since 2012

@nayafia

But only 1.7M repos on GitHub have CONTRIBUTING.md or .rst

(roughly 5-11% out of 35M or ~17M repos, depending how you count it)

@nayafia

Referencing this study from last year...

@nayafia

alexreisner/geocoder, celery/celery, gruntjs/grunt, mbostock/d3, sass/sass, ansible/ansible, cucumber/cucumber, clojure/clojure, plataformatec/devise, haml/haml, bundler/bundler, jekyll/jekyll, jquery/jquery, django/django, android/platform_frameworks_base, homebrew/homebrew, etcetcetc

@nayafia

Half of projects listed with a Truck Factor of 1 don’t have CONTRIBUTING.md

@nayafia

A third of projects listed with Truck Factor of 2 don’t have CONTRIBUTING.md

@nayafia

We don’t want you to get hit by a truck, but if you did...

@nayafia

...how would your project live on??

@nayafia

Why should you care about contributing guides?

@nayafia

Contributing guides help clarify your commitment

@nayafia

Contributing guides help your project grow

@nayafia

Contributing guides mean you have to do less work

@nayafia

What do good contributing guides look like?

@nayafia

Looked at 40 projects: ½ on small side, ¼ medium, ¼ large**** this is totally handwavy gutfeel stuff based on what I vaguely know about who’s contributing to and using these projects. plz forgive

@nayafia

Good guides cover basically the same things, regardless of size

@nayafia

I’ll spare you the boring stuff. Go here:

https://github.com/nayafia/contributing-template

@nayafia

But here are some highlights:

@nayafia

Write a friendly introduction

@nayafia

Ask for the contributions you want

Tell them what you are or aren’t looking for, ask for help on known issues, etc.

@nayafia

Create a “Your First Contribution” section

@nayafia

Use templates and label conventions

Standardized stuff makes your life easier.

@nayafia

Explain security disclosures

At bare minimum, let them know that if they find a security issue, they should contact you privately, and tell them how to reach you.

@nayafia

Questions?

https://github.com/nayafia/contributing-template