Open Source Maintenance — RailsClub Moscow

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