A beginners guide to contributing open source

A talk I gave at Ruby on Rails Oceania Sydney on 12th August 2014.

Transcript

1. A B E G I N N E R S G U I D E T O C O N T R I B U T I N G O P E N S O U R C E C O D E ! R O B S H A R P H E A D O F T E C H N O L O G Y @ R AT E C I T Y. C O M . A U ! P L A Y S W E L L W I T H O T H E R S
2. • Open-source software (OSS) is computer software with its source code made available with a license in which the copyright holder provides the rights to study, change and distribute the software to anyone and for any purpose. [Wikipedia]
3. C O N S I D E R Y O U R S TA C K • HAML [MIT] • Rails [MIT] • MRI Ruby [BSD] • Postgres [PostgresQL, like BSD/MIT] • Unicorn [GPL3] • Nginx [BSD]
4. W H AT S H O U L D I W O R K O N ? • Follow your heart • Failing that, scratch an itch
5. W H AT D I D I D O ? • I scratched an itch ! ! • remote_table present tabular data from in a variety of formats in a nice Enumerable data structure • Oddly, missing JSON support
6. W H AT D I D I D O ? 1. Worked out how the current handlers work 2. Determined a close match to borrow structure from 3. Wrote tests for the new behaviour 4. Implemented the new behaviour 5. Documented the new behaviour 6. PR
7. D I G G I N G A R O U N D C O D E • To add JSON, first understand YAML
8. D I G G I N G A R O U N D C O D E
9. W H AT D I D I D O ? 1. Worked out how the current handlers work 2. Determined a close match to borrow structure from 3. Wrote tests for the new behaviour 4. Implemented the new behaviour 5. Documented the new behaviour 6. PR
10. T I M E PA S S E S • Create tests to support the intended changes • Model tests on existing uses of the API
12. W H AT D I D I D O ? 1. Worked out how the current handlers work 2. Determined a close match to borrow structure from 3. Wrote tests for the new behaviour 4. Implemented the new behaviour 5. Documented the new behaviour 6. PR
13. I M P L E M E N T • Keep to existing conventions • Existing YML Code <—-> New JSON Code
14. W H AT D I D I D O ? 1. Worked out how the current handlers work 2. Determined a close match to borrow structure from 3. Wrote tests for the new behaviour 4. Implemented the new behaviour 5. Documented the new behaviour 6. Pull Request
15. D O C U M E N T D O C U M E N T D O C U M E N T • The biggest failing in Open Source is documentation. • You’re better than that - show off!
16. P U L L R E Q U E S T S • Always squash before submitting a PR • Comment your code • Check the contributors guide for weird stuff
17. C O N T R I B U T I N G . M D • Smart maintainers are explicit in their requirements
18. R E A D M E . M D • Some repos are a little more cryptic
19. • “Committing your code to anothers repository is asking the maintainer to look after it indefinitely”
20. C O N T R I B U T I O N PAT T E R N S • Scratch an itch • Understand the repo aesthetic • Tread lightly on the API • Write tests • Document your code like I’m five • Be polite
21. Q U E S T I O N S ?