Let's make gem development fun and not at all repetitive! A set of common tasks which should save you a fair bit of typing and give you more time for doing useful things with your life.
Ruby
Pull request Compare This branch is 86 commits behind joshbuddy:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
spec
.gitignore
CHANGELOG
Gemfile
Gemfile.lock
README.rdoc
Rakefile
Tumbler
tumbler.gemspec

README.rdoc

Tumbler

Let's make gem development fun and remove all the repetition! Tumbler provides support for common gem management tasks which helps you spend less time dealing with gem releases and more time focusing on your gem functionality!

Gem Guidelines

Tumbler was built to help developers create and manage gems using a common set of 'best practices' out of the box. Tumbler also makes a number of assumptions about your workflow:

  • Gem uses directly edited dynamic gemspecs

  • Gem uses Git to manage code source (perhaps on Github)

  • Git tags are created for each new version

  • Gem dependencies are defined using a Gemfile through Bundler

If your gem can follow these guidelines, then Tumbler will automate the entirety of this process for you into rake tasks.

Using Tumbler

Creating Gems

To generate a brand new gem from scratch, execute the following:

$ tumbler your_gem_name

This will generate a skeleton of your gem that you can then easily configure and start building awesome.

Existing Gems

If you have a pre-existing gem which could benefit from Tumbler, you have to a do a few things. Note that if you are generating a new gem using the tumbler command, this will be done for you automatically.

For existing projects, you need to instruct Tumbler to manage the gem tasks. This is all handled by a file at the root of your project called Tumbler. A typical Tumbler file should look something like the following:

# Names your gem
gem_name 'my_awesome_gem'

# Use this file to track the version number
version_file 'lib/my_awesome_gem/version.rb'

# Use this file for your changelog
changelog_file 'CHANGELOG'

Your version number can be anything parsable by Versionomy. The changelog will be automatically updated when a new version is released.

The version file should have a constant VERSION which is set to the current version for your gem. A typical version file might look like the following:

# lib/awesome_gem/version.rb
module AwesomeGem #:nodoc
  VERSION = '0.0.1'
end

Next, in your Rakefile, add the following to get access to Tumbler tasks:

require 'tumbler'
Tumbler.use_rake_tasks

Alternatively, you can have Tumbler do all this work for you. If you install Tumbler into your system gems, you can simply execute:

tumbler . -u --name gem_name

From inside the gem's root directory and this will take care of all these details for you.

Available Rake Tasks

Once you've got Tumbler up and running in your gem, you will have access to the following tasks:

rake gem:build              # Build the gem
rake gem:install            # Install the gem
rake gem:push               # Push the gem
rake version:major:bump     # Bump version from 0.2.12 ->  1.0.0
rake version:minor:bump     # Bump version from 0.2.12 ->  0.3.0
rake version:tiny:bump      # Bump version from 0.2.12 ->  0.2.13
rake version:major:release  # Bump version from 0.2.12 ->  1.0.0 and push
rake version:minor:release  # Bump version from 0.2.12 ->  0.3.0 and push
rake version:tiny:release   # Bump version from 0.2.12 ->  0.2.13 and push
rake version:push           # Push current version into git
rake version:tag            # Tag current version into git

Releasing your Gem

You can either do

rake version:(tiny|minor|major):release

which will bump the version, tag it in git, regenerate the changelog from your git commits and push the whole thing to rubygems and your remote or you can do it in two separate steps:

rake version:(tiny|minor|major):bump
rake version:push

This will give you the chance to review the changelog and do anything else you'd like before taking the final release plunge.

Common Workflow

Here is an example of a common usage for Tumbler. Let's say I want to create a new gem. Let's walk through the process:

$ tumbler your_gem_name
$ cd your_gem_name

This will generate the basic gem structure. Now we need to configure the 'your_gem_name.gemspec' with gem details and configure 'Gemfile' with the external dependencies. That's all you need to get started! From here, simply implement your gem. When ready for your first release you should first test locally:

# test your gem locally
$ rake gem:install

When you feel confident and you are ready to push your first version to git and rubygems, simply invoke:

# releases your gem
$ rake version:tiny:release

and that does it! Your gem is now released onto the world.

What's next?

I'm sure there are bugs and other common workflows that I will add and/or document, but basically, I just wanna type a lot less when I bump a gem, and get more things done.