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