What makes a good open source contributing guide? Highlights and best practices from research. From an Open Source Show and Tell talk in San Francisco, April 22 2016. Template referenced in the talk can be found here: https://github.com/nayafia/contributing-template FOOTNOTES Slides 3 and 4: Based on GitHub Search conducted Apr 18 2016. Thanks Brandon Keepers (@bkeepers) for helping with this! Slides 5 and 6: https://peerj.com/preprints/1233.pdf Slides 7 and 8: Current as of Apr 18 2016 Slide 20: http://read-the-docs.readthedocs.org/en/latest/contribute.html Slide 21: https://github.com/plataformatec/devise/wiki/Contributing Slide 22: https://docs.djangoproject.com/en/dev/internals/contributing/new-contributors/#guidelines Slide 23: https://github.com/angular/material/blob/master/CONTRIBUTING.md#-git-commit-guidelines Slide 24: https://github.com/celery/celery/blob/master/CONTRIBUTING.rst#security

1. @nayafia
Designing Useful
Contributing Guides
@nayafia for OSSAT

2. @nayafia
Contributing guides tell
people how to contribute
to your project

3. @nayafia
GitHub has
recognized
CONTRIBUTING.md
as a standard since
2012

4. @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)

5. @nayafia
Referencing this
study from last
year...

6. @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

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

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

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

10. @nayafia
...how would your
project live on??

11. @nayafia
Why should you
care about
contributing guides?

12. @nayafia
Contributing guides
help clarify your
commitment

13. @nayafia
Contributing guides
help your project
grow

14. @nayafia
Contributing guides
mean you have to do
less work

15. @nayafia
What do good
contributing guides
look like?

16. @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

17. @nayafia
Good guides cover
basically the same
things, regardless of
size

18. @nayafia
I’ll spare you the
boring stuff. Go here:
https://github.
com/nayafia/contributing-
template

19. @nayafia
But here are some
highlights:

20. @nayafia
Write a friendly
introduction

21. @nayafia
Ask for the
contributions you want
Tell them what you are or aren’t looking for, ask for help on known issues, etc.

22. @nayafia
Create a “Your First
Contribution” section

23. @nayafia
Use templates and
label conventions
Standardized stuff makes your life easier.

24. @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.

25. @nayafia
Questions?
https://github.
com/nayafia/contributing-
template