Writing Ruby Gems & Contributing to OSS in the Github Age

Jeremy Olliver @static_storm

What Does a Ruby Gem look like?

gemspec le ruby source les 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 bundle new my_project sow my_project

bundler hoe

Jeweler
Has the most unecessary baggage of all the
tools

Keeps conguration inside Rakele (auto

generates gemspec)

Good readme content for contributions

Bundler
Uses gemspec for conguration Gemle references the gemspec keeps to convention of module layout/
cong

Hoe
Similar to jeweler, congures via Rakele provides templating functionality setup your own templates in
~/.hoe_template

Executables and Cextensions

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

Some Real Examples

<See actual gem source> 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 doesnt matter (test unit,
rspec, mini test), just having them present is the important part providing a ci server that will run your tests on multiple ruby implementations contribute and you to accept patches

travis-ci is a nice distributed build server no tests makes it hard for others to

Versioning
Dening the version as a namespaced
runtime dependencies major.minor.patch) constant is nice (e.g. MyGem::VERSION)

remember to specify your development & Use Semantic Versioning (X.Y.Z ->

Semantic Versioning

format: major.minor.patch use alpha characters after for pre releases (1.4.3.beta3) Increment patch level for bug xes, optimisation and other small changes. minor level for backwards compatible features (this one is used more uidly 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 take the time to explain your project (goals, tradeoffs, and importantly how to get started using it)

readme driven development:

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 git remote add otherguy git://..... git pull otherguy feature_x

accepting patches:

github new web editor steamlines even more

Resources
http://incitecode.com (my blog) http://guides.rubygems.org/ https://github.com/zenspider/ruby-cexample

http://tenderlovemaking.com/2009/12/18/writingruby-c-extensions-part-1/ Jeremy Olliver @static_storm