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!
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.
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.
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
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.
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.
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.