Designing Useful Contributing Guides (OSSAT Talk)
Designing Useful Contributing Guides (OSSAT Talk)
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
Recommended
More Related Content
Recently uploaded
![[DPE Summit] How Improving the Testing Experience Goes Beyond Quality: A Deve...](https://cdn.slidesharecdn.com/ss_thumbnails/dpesummitseptember20-212023-howimprovingthetestingexperiencegoesbeyondqualityadeveloperproductivityp-230924000523-453e8af8-thumbnail.jpg?width=1600&height=908&fit=bounds)
Featured
Designing Useful Contributing Guides (OSSAT Talk)
- 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:
- 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.