Slide 1

Slide 1 text

Writing Ruby Gems & Contributing to OSS in the Github Age Jeremy Olliver @static_storm

Slide 2

Slide 2 text

What Does a Ruby Gem look like? • gemspec file • ruby source files • documentation • executable scripts (optional) • c-extensions (optional) • this is all you need to build, install and run

Slide 3

Slide 3 text

Gem Development Tools • Provide some helper methods, though can add unnecessary overhead • jeweler (oldest) • jeweler my_project • bundler • bundle new my_project • hoe • sow my_project

Slide 4

Slide 4 text

Jeweler • Has the most unecessary baggage of all the tools • Keeps configuration inside Rakefile (auto generates gemspec) • Good readme content for contributions

Slide 5

Slide 5 text

Bundler • Uses gemspec for configuration • Gemfile references the gemspec • keeps to convention of module layout/ config

Slide 6

Slide 6 text

Hoe • Similar to jeweler, • configures via Rakefile • provides templating functionality • setup your own templates in ~/.hoe_template

Slide 7

Slide 7 text

Executables and C- extensions • executables live in ./bin • executables are nothing more than ruby files requiring and running your own code • c-extensions live in ./ext and use an extconf.rb to generate a makefile (rest is out of scope) refer to: • http://tenderlovemaking.com/2009/12/18/writing-ruby-c- extensions-part-1/ • http://tenderlovemaking.com/2010/12/11/writing-ruby-c- extensions-part-2/

Slide 8

Slide 8 text

Some Real Examples • • When developing for use with other bundler based projects (e.g. a rails extension): • gem ‘name’, :git => “git://...” • gem “name, :path => “../my_gem”

Slide 9

Slide 9 text

Building and Distributing Gems • gem build my_cool_code.gemspec • gem install my_cool_code-0.0.1.gem • signup on rubygems.org then: • gem push my_cool_code-0.0.1.gem

Slide 10

Slide 10 text

Convention • Naming: • try to pick a google friendly and not already taken name for the gem • use snake_case for gem names • only use dashes for extending existing gems e.g. rack-cache, capistrano-ext • modules are your friend

Slide 11

Slide 11 text

Tests • Framework doesn’t matter (test unit, rspec, mini test), just having them present is the important part • travis-ci is a nice distributed build server providing a ci server that will run your tests on multiple ruby implementations • no tests makes it hard for others to contribute and you to accept patches

Slide 12

Slide 12 text

Versioning • Defining the version as a namespaced constant is nice (e.g. MyGem::VERSION) • remember to specify your development & runtime dependencies • Use Semantic Versioning (X.Y.Z -> major.minor.patch)

Slide 13

Slide 13 text

Semantic Versioning • format: major.minor.patch • use alpha characters after for pre releases (1.4.3.beta3) • Increment patch level for bug fixes, optimisation and other small changes. • minor level for backwards compatible features (this one is used more fluidly in practice) • major level for non backwards compatible • tag versions in your source (git tag v1.3.4 && git push --tags) • allows for use of pessimistic versioning for your users ‘~> 2.1’ implies ‘< 3.X’

Slide 14

Slide 14 text

Make Your Code Accessible • write clean code (duh) • documentation (rdoc, yard) • rubygems builds yard docs at rubydoc.info • run yard locally with ‘yard server’ • readme driven development: • take the time to explain your project (goals, tradeoffs, and importantly how to get started using it) • Consider what API you would want to use yourself

Slide 15

Slide 15 text

OSS on Github • README should contain all the basics • when submitting a bug report, be thorough and polite • submit a patch: • fork, use a branch per bug/feature • accepting patches: • git remote add otherguy git://..... • git pull otherguy feature_x • github new web editor steamlines even more

Slide 16

Slide 16 text

Resources • http://incitecode.com (my blog) • http://guides.rubygems.org/ • https://github.com/zenspider/ruby-c- example • http://tenderlovemaking.com/2009/12/18/writing- ruby-c-extensions-part-1/ Jeremy Olliver @static_storm