Open Source Maintenance — RailsClub Moscow

Presented at RailsClub Moscow 2013

Transcript

1. Open Source Maintenance Eric Hodel - drbrain@segment7.net
2. Open Source is My Job
3. Projects •RubyGems •RDoc •net-http-persistent •… many more
4. Responsibilities Maintenance Stewardship Understanding
5. Why Open Source?
6. “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
7. “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
8. “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
9. I Care
10. Pleasant Surprises net-http-persistent single connection ~750,000 requests
11. Pleasant Surprises rdoc -C shows documentation coverage for your library used in contracts
12. Values
13. Open Source Values •Community •Collaboration •Sharing •Re-use
14. Proprietary Software “Your team should work like an open source project” bit.ly/1byoEiK Ryan Tomayko
15. OSS Constraints •Electronic Communication •Visible Work •Asynchronous •Lock-free
16. Commits
17. Commits Create History
18. Tell a Story
19. Commit Small •History is easier to read •Easy to revert •Easy branch maintenance •github user page bragging
20. Atomic Commit Convention bit.ly/160ia91
21. Small Commits •Fix only one bug •Add one method •Whitespace cleanup •Reformat a line
22. Current status: Not sure where I was going with this
23. “One thing Clojure has taught me is that good commit messages are a luxury of people that know what […] they are doing” @tpope
24. Be Descriptive Descriptive messages make history easy to understand
25. git commit --help “begin the commit message with a single short line summarizing the change”
26. 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`
27. git commit --help “followed by a more thorough description”
28. 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.
29. Thorough Description •Old behavior •Why it needs to change •New behavior
30. Thorough Description •Commit references •Issue references •Don't assign blame •Except to yourself
31. Issues
32. Organize
33. Issue Labels •Status •Type •Category
34. Milestones •Release boundary •Allow slippage •Feature freeze
35. Keep an Open Mind
36. Random Test Failure -{"SHA512"=> +{"SHA1"=>
37. Random Test Failure •Rarely occurs •Probably hash order problem •Must be hash order problem!
38. Hash Mismatch +"data.tar.gz"=>"14413052..."}, -"data.tar.gz"=>"c6465bbb..."},
39. gzip Timestamp •One second resolution •Test gzipped two files •Sometimes in different seconds
40. It's OK to Be Wrong
41. rubygems/rubygems #510 them: The chmod should be included in the publishing guide
42. rubygems/rubygems #510 me: Why? The file is created with the correct permissions
43. rubygems/rubygems #510 them: The guide says to run: curl -u username [...] > ~/.gem/credentials
44. 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.
45. Pursue Understanding
46. “‘X’ is Hard to Use” •“Hard”, “Broken”, “Doesn't Work” •You think “X” is easy, works •They might be right!
47. Maintenance & New Features
48. Find the Root Cause
49. “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
50. Hard → Easy •Hide details when possible •Avoid configuration •Provide broad defaults
51. “The worst thing about writing clever code is not being clever enough to understand it.” Eleanor McHugh — @feyeleanor
52. Keep it Simple •Small commits •Minimum change •Document when you can't
53. 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”
54. Refactor •Simplify methods •Improve API •Improve understanding •Don't forget tests
55. Good API
56. Compact API •Minimum objects •Minimum arguments •Minimum configuration •Self-check through tests
57. Good Names •Hardest •Do your names fit? •Reveal intention?
58. Semantic Versioning
59. 2.3.4 •Incompatible API changes
60. 2.3.4 •Incompatible API changes •Backward-compatible features
61. 2.3.4 •Incompatible API changes •Backward-compatible features •Backward-compatible bug fixes •http://semver.org
62. SemVer and RubyGems 'rake', '~> 10.0.3' 10.0.3 to 10.0.99…
63. SemVer and RubyGems 'rake', '~> 10.0', '>= 10.0.3' 10.0.3 to 10.99…
64. Reduce Barriers
65. “This is what your tool chain looks like to people not ‘in the know’. They just want to do a thing” @jessenoller
66. How Do I Start? •CONTRIBUTING.txt •run: bundle •How do I run the tests? •hoe: rake newb
67. CONTRIBUTING.txt •Your process •fork, edit, test, pull request •Code conventions •Vocabulary
68. Automate Everything •Travis-CI •Generate files •Run tests •Release
69. How to Contribute
70. What Gems do You Use?
71. Gems You Use •Report bugs •Report bad documentation •Hard to understand •Missing examples
72. Pull Requests •Contact the maintainers: “How would I fix issue #XXX” •Start small •Try different projects
73. Scratch Your Own Itch
74. Code Climate •Free for github projects •Uses flog and flay •Refactoring targets •Method duplication •Complexity
75. Thank You