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

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 

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 

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

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

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

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/ 

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” 

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 

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 

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 

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) 

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’ 

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 

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 

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