Your First Ruby Gem

UPDATE: I did another iteration of live-coding a Ruby gem at Flatiron School in January 2018. The code, a very similar but more complete and up-to-date checklist is here.

I live-coded a new gem called Ruby::Enum at NYC.rb on Tuesday. This library adds enum-like functionality to Ruby.

Here’s my checklist for creating a new gem.

Check the Name

Ruby gems are registered with Rubygems and managed in your projects using Bundler. Search for the new gem name on Rubygems to make sure it’s not taken.

Create a Folder

I organize all my code in source and since I often fork code from others to contribute, create a subfolder with the Github username, including mine.

$ mkdir ~/source/ruby-enum/dblock
$ cd ~/source/ruby-enum/dblock

Initialize a Git Repository

$ git init
Initialized empty Git repository in /home/dblock/source/ruby-enum/dblock/.git/

Create a Github Repo

Create a new repository on Github.

Add it as a remote.

$ git remote add origin git@github.com:dblock/ruby-enum.git

Create a Readme

Documentation is written in Markdown. Create and commit a README.md.

$ git commit -m "Added README."
[master acc5880] Added README.
1 file changed, 4 insertions(+)
create mode 100644 README.md

Push the README to Github.

$ git push origin master
Counting objects: 6, done.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (6/6), 963 bytes, done.
Total 6 (delta 0), reused 0 (delta 0)
To git@github.com:dblock/ruby-enum.git
* [new branch]      master -> master

Add a License

Every project needs a license. I use the MIT license because it’s short and nobody has time to read licenses. Add a copyright notice to the README, don’t forget future contributors.

Copyright (c) 2013, Daniel Doubrovkine and Contributors. All Rights Reserved.
This project is licenced under the [MIT License](LICENSE.md).

Gemfile

A Gemfile is something that comes with Bundler and declares gem dependencies.

Install Bundler.

$ gem install bundler
Fetching: bundler-1.3.5.gem (100%)
Successfully installed bundler-1.3.5
1 gem installed
Installing ri documentation for bundler-1.3.5...
Installing RDoc documentation for bundler-1.3.5...

Create a Gemfile. For now it just says where to get other gems from.

source "https://rubygems.org"

Run bundle install.

$ bundle install
Resolving dependencies...
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

.gitignore

The generated Gemfile.lock should not be included, create a .gitignore.

Gemfile.lock

Enum Library

Create lib/ruby-enum.rb _and _lib/ruby-enum/version.rb.

require 'ruby-enum/version'

module Ruby::Enum
  VERSION = '0.1.0'
end

Tests

You. Must. Test.

Add RSpec to Gemfile.

gem "rspec"

Tests need some setup, specifically to load the code in lib. Create spec/spec_helper.rb.

$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))

require 'rubygems'
require 'rspec'
require 'ruby-enum'

Create a test in spec/ruby-enum/version.rb.

require 'spec_helper'
describe Ruby::Enum do
  it "has a version" do
    Ruby::Enum::VERSION.should_not be_nil
  end
end

Add .rspec to pretty-print test output.

--format documentation
--color

Gem Declaration

A ruby-enum.gemspec is a gem declaration.

$:.push File.expand_path("../lib", __FILE__)
require "ruby-enum/version"
Gem::Specification.new do |s|
  s.name = "ruby-enum"
  s.version = Ruby::Enum::VERSION
  s.authors = ["Daniel Doubrovkine"]
  s.email = "dblock@dblock.org"
  s.platform = Gem::Platform::RUBY
  s.required_rubygems_version = '>= 1.3.6'
  s.files = `git ls-files`.split("\n")
  s.require_paths = ["lib"]
  s.homepage = "https://github.com/dblock/ruby-enum"
  s.licenses = ["MIT"]
  s.summary = "Enum-like Behavior for Ruby"
end

The declaration can be loaded in Gemfile, so that we can list dependencies in one place.

source "https://rubygems.org"
gemspec

When running under Bundler, the Gemfile will automatically be loaded, which will automatically load the gem specification.

$ bundle exec irb
1.9.3-p362 :001 > require 'ruby-enum'
=> true
1.9.3-p362 :002 > Ruby::Enum::VERSION
=> "0.1.0"

Rakefile

Bundler comes with a number of Rake tasks to release a gem. Add Rake to Gemfile.

gem "rake"

Create a Rakefile.

require 'rubygems'
require 'bundler/gem_tasks'
Bundler.setup(:default, :development)

$ rake -T
rake build    # Build ruby-enum-0.1.0.gem into the pkg directory.
rake install  # Build and install ruby-enum-0.1.0.gem into system gems.
rake release  # Create tag v0.1.0 and build and push ruby-enum-0.1.0.gem to Rubygems

$ rake build
ruby-enum 0.1.0 built to pkg/ruby-enum-0.1.0.gem.

Add pkg to .gitignore.

Default Rakefile to Running Tests

require 'rspec/core'
require 'rspec/core/rake_task'

RSpec::Core::RakeTask.new(:spec) do |spec|
  spec.pattern = FileList['spec/**/*_spec.rb']
end

task :default => :spec

Travis-CI

Add .travis.yml, register the project on travis-ci.org and add a badge.

rvm:
  - 1.8.7
  - 1.9.3
  - 2.0.0
  - jruby-19mode
  - rbx-19mode

[![Build Status](https://travis-ci.org/dblock/ruby-enum.png)](https://travis-ci.org/dblock/ruby-enum)

Enum Library Code

Include ruby-enum/enum. See enum.rb and enum_spec.rb for the implementation.

Changelog

Create a CHANGELOG to list current and future updates.

### 0.1.0 (5/14/2013)

* Initial public release - [@dblock](https://github.com/dblock).

Contributing

Add a contributing section to README.

* Fork the project.
* Make your feature addition or bug fix with tests.
* Update CHANGELOG.
* Send a pull request. Bonus points for topic branches.

Release the Gem

$ rake release

Prepare for Next Release

Bump the version, add a Next Release section to CHANGELOG.md.

### Next Release (TBD)

* Your Contribution Here

Source Code

All source code for the above can be found at https://github.com/dblock/ruby-enum.

Daniel Doubrovkine

Your First Ruby Gem ruby | open source