Successfully reported this slideshow.

Designing Useful Contributing Guides (OSSAT Talk)

2

Share

Upcoming SlideShare
Rebuilding the cathedral
Rebuilding the cathedral
Loading in …3
×
1 of 25
1 of 25

Designing Useful Contributing Guides (OSSAT Talk)

2

Share

Download to read offline

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

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

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Related Audiobooks

Free with a 14 day trial from Scribd

See all

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

×