Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Open Source Maintenance — Ruby on Ales 2014

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.


Eric Hodel

March 07, 2014

More Decks by Eric Hodel

Other Decks in Programming


  1. Open Source Maintenance Eric Hodel - drbrain@segment7.net

  2. Jury Duty

  3. None
  4. None
  5. None
  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

  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

  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

  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

  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

  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