Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
@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...
@nayafia
Referencing this
study from last
year...
@nayafia
alexreisner/geocoder, celery/celery,
gruntjs/grunt, mbostock/d3,
sass/sass, ansible/ansible,
cucumber/cucumber, c...
@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 wh...
@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, et...
@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 conta...
@nayafia
Questions?
https://github.
com/nayafia/contributing-
template
Upcoming SlideShare
Loading in …5
×

Designing Useful Contributing Guides (OSSAT Talk)

894 views

Published on

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

Published in: Software
  • Be the first to comment

Designing Useful Contributing Guides (OSSAT Talk)

  1. 1. @nayafia Designing Useful Contributing Guides @nayafia for OSSAT
  2. 2. @nayafia Contributing guides tell people how to contribute to your project
  3. 3. @nayafia GitHub has recognized CONTRIBUTING.md as a standard since 2012
  4. 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. 5. @nayafia Referencing this study from last year...
  6. 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. 7. @nayafia Half of projects listed with a Truck Factor of 1 don’t have CONTRIBUTING.md
  8. 8. @nayafia A third of projects listed with Truck Factor of 2 don’t have CONTRIBUTING.md
  9. 9. @nayafia We don’t want you to get hit by a truck, but if you did...
  10. 10. @nayafia ...how would your project live on??
  11. 11. @nayafia Why should you care about contributing guides?
  12. 12. @nayafia Contributing guides help clarify your commitment
  13. 13. @nayafia Contributing guides help your project grow
  14. 14. @nayafia Contributing guides mean you have to do less work
  15. 15. @nayafia What do good contributing guides look like?
  16. 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. 17. @nayafia Good guides cover basically the same things, regardless of size
  18. 18. @nayafia I’ll spare you the boring stuff. Go here: https://github. com/nayafia/contributing- template
  19. 19. @nayafia But here are some highlights:
  20. 20. @nayafia Write a friendly introduction
  21. 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. 22. @nayafia Create a “Your First Contribution” section
  23. 23. @nayafia Use templates and label conventions Standardized stuff makes your life easier.
  24. 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. 25. @nayafia Questions? https://github. com/nayafia/contributing- template

×