Open Source Maintenance — Ruby on Ales 2014

Maintaining RubyGems, RDoc and other Ruby libraries has grown from a hobby to my full time job over the past six years. Working on and maintaining open source projects has brought me lots of fun and enjoyment. I'll cover the joy and pain of being an open source developer, strategies for maintaining both your project and the interest and happiness you derive from it. I'll also talk about some of the things that keep me motivated to continue working on open source.

Transcript

1. Open Source Maintenance Eric Hodel - drbrain@segment7.net
2. Jury Duty
6. Open Source is My Job
7. Projects •RubyGems •RDoc •net-http-persistent •… many more
8. Responsibilities Maintenance Stewardship Understanding
9. Why Open Source?
10. “programming is rather thankless. you see your works become replaced by superior works in a year. unable to run at all in a few more.” _why
11. “Here’s what becoming eFamous made me realize: Everyone is sincere and doing it because they care. I was very surprised to learn this.” @garybernhardt
12. “I get paid to do something I love. Something I’ve done in my spare time since I was a kid. That’s awesome. That’s why I care.” @lindseybieda
13. I Care
14. Pleasant Surprises net-http-persistent single connection ~750,000 requests
15. Pleasant Surprises rdoc -C shows documentation coverage for your library used in contracts
16. Values
17. Open Source Values •Community •Collaboration •Sharing •Re-use
18. Proprietary Software “Your team should work like an open source project” bit.ly/1byoEiK Ryan Tomayko
19. OSS Constraints •Electronic Communication •Visible Work •Asynchronous •Lock-free
20. Commits
21. Commits Create History
22. Tell a Story
23. Commit Small •History is easier to read •Easy to revert •Easy branch maintenance •github user page bragging
24. Atomic Commit Convention bit.ly/160ia91
25. Small Commits •Fix only one bug •Add one method •Whitespace cleanup •Reformat a line
26. Current status: Not sure where I was going with this
27. “One thing Clojure has taught me is that good commit messages are a luxury of people that know what the fuck they are doing” @tpope
28. Be Descriptive Descriptive messages make history easy to understand
29. git commit --help “begin the commit message with a single short line summarizing the change”
30. Short Summary •The URI argument to Gem::Request.new must be a URI •Only display relevant release notes upon update •Allow `gem uninstall foo --all`
31. git commit --help “followed by a more thorough description”
32. Thorough Description The URI argument to Gem::Request.new must be a URI The tests were lazy and used a String which was converted internally. This causes problems on older ruby versions which don't allow `URI(URI("http://example"))`. Now the argument given is always a URI in the tests.
33. Thorough Description •Old behavior •Why it needs to change •New behavior
34. Thorough Description •Commit references •Issue references •Don't assign blame •Except to yourself
35. Issues
36. Organize
37. Issue Labels •Status •Type •Category
38. Milestones •Release boundary •Allow slippage •Feature freeze
39. Keep an Open Mind
40. Random Test Failure -{"SHA512"=> +{"SHA1"=>
41. Random Test Failure •Rarely occurs •Probably hash order problem •Must be hash order problem!
42. Hash Mismatch +"data.tar.gz"=>"14413052..."}, -"data.tar.gz"=>"c6465bbb..."},
43. gzip Timestamp •One second resolution •Test gzipped two files •Sometimes in different seconds
44. It's OK to Be Wrong
45. rubygems/rubygems #510 them: The chmod should be included in the publishing guide
46. rubygems/rubygems #510 me: Why? The file is created with the correct permissions
47. rubygems/rubygems #510 them: The guide says to run: curl -u username [...] > ~/.gem/credentials
48. rubygems/rubygems #510 me: I'm sorry, I didn't read that section. RubyGems creates the credentials file for you. I'll rewrite the offending section.
49. Pursue Understanding
50. “‘X’ is Hard to Use” •“Hard”, “Broken”, “Doesn't Work” •You think “X” is easy, works •They might be right!
51. Maintenance & New Features
52. Find the Root Cause
53. “Trying to force myself to keep asking, ‘rather than *solve* [hard problem X], is there a way to make [X] irrelevant?’ Typical answer: yes.” Kathy Sierra — @seriouspony
54. Hard → Easy •Hide details when possible •Avoid configuration •Provide broad defaults
55. pcaprub API pcap = Pcap.open_live 'wlan0', 65535, true, 0 pcap.setfilter 'icmp' loop do p pcap.next end
56. capp capp = Capp.live capp.filter = 'icmp' capp.loop do |packet| p packet end
57. “The worst thing about writing clever code is not being clever enough to understand it.” Eleanor McHugh — @feyeleanor
58. Keep it Simple •Small commits •Minimum change •Document when you can't
59. rails/rails@ba0568e “In the past we used Hash[columns.zip(row)] […], the verbose way is much more efficient both time and memory wise cause it avoids a big array allocation”
60. Refactor •Simplify methods •Improve API •Improve understanding •Don't forget tests
61. Good API
62. Compact API •Minimum objects •Minimum arguments •Minimum configuration •Self-check through tests
63. Good Names •Hardest •Do your names fit? •Reveal intention?
64. Semantic Versioning
65. 2.3.4 •Incompatible API changes
66. 2.3.4 •Incompatible API changes •Backward-compatible features
67. 2.3.4 •Incompatible API changes •Backward-compatible features •Backward-compatible bug fixes •http://semver.org
68. SemVer and RubyGems 'rake', '~> 10.0.3' 10.0.3 to 10.0.99…
69. SemVer and RubyGems 'rake', '~> 10.0', '>= 10.0.3' 10.0.3 to 10.99…
70. Reduce Barriers
71. “This is what your tool chain looks like to people not ‘in the know’. They just want to do a thing” @jessenoller
72. How Do I Start? •CONTRIBUTING.txt •run: bundle •How do I run the tests? •hoe: rake newb
73. CONTRIBUTING.txt •Your process •fork, edit, test, pull request •Code conventions •Vocabulary
74. Automate Everything •Travis-CI •Generate files •Run tests •Release
75. How to Contribute
76. What Gems do You Use?
77. Gems You Use •Report bugs •Report bad documentation •Hard to understand •Missing examples
78. Pull Requests •Contact the maintainers: “How would I fix issue #XXX” •Start small •Try different projects
79. Scratch Your Own Itch
80. Code Climate •Free for github projects •Uses flog and flay •Refactoring targets •Method duplication •Complexity
81. Thank You