Writing Rubygems & Contributing to OSS in the Github Age

A talk on how to get started writing your own gems, and contributing to others, and how easy it is to get involved in contributing to open source projects with Github

Transcript

1. Writing Ruby Gems & Contributing to OSS in the Github Age Jeremy Olliver @static_storm
2. 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
3. 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
4. Jeweler • Has the most unecessary baggage of all the tools • Keeps configuration inside Rakefile (auto generates gemspec) • Good readme content for contributions
5. Bundler • Uses gemspec for configuration • Gemfile references the gemspec • keeps to convention of module layout/ config
6. Hoe • Similar to jeweler, • configures via Rakefile • provides templating functionality • setup your own templates in ~/.hoe_template
7. 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/
8. 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”
9. 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
10. 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
11. 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
12. 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)
13. 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’
14. 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
15. 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
16. 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