Jeweler turns 1.0.0
There’s always a certain amount of stigma, fear, and uncertainty around the doing the big 1.0 release. I finally got over that for Jeweler. So, be hold! Jeweler 1.0.0.
For the uninitiated, Jeweler is a tool for creating and managing RubyGems projects. It lets you quickly go from 0 to released gem. It also simplifies managing your gem after you create it.
There are two main components to jeweler: the generator for creating an initial project, and the rake tasks for managing versioning and releases.
Install it
sudo gem install jeweler
The generator
The simplest incantation of the jeweler is this:
jeweler your-awesome-gem
This creates a local git repository with a basic skeleton for your project. It includes things like a Rakefile, a template to put your gem’s code in, a test helper, a failing test case, and a LICENSE. It also setup to be pushed to GitHub and includes a reasonable gitignore file.
By default, you’ll get Shoulda flavored tests, but you can opt to go with test/unit, minitest, rspec, bacon, or micronaut. For example:
jeweler —micronaut your-awesome-gem
If you want to use cucumber, you can have that too. It’ll be setup for whichever testing framework you choose:
jeweler —micronaut —cucumber your-awesome-gem
You can also choose to have a repository created for you on GitHub, with RubyGem creation enabled:
jeweler —create-repo your-awesome-gem
While originally intended specifically to work with GitHub’s gem support, it eventually was realized that it’d be nice to release to RubyForge too. You can add support to your project:
jeweler —rubyforge your-awesome-gem
If you look at your Rakefile, you’ll notice that a number of tasks were generated for you. Jeweler itself provides a number of tasks, as mentioned, but it also tasks for rdoc, test or spec, and rcov. However, your Rakefile doesn’t depend specifically on jeweler. This means that someone randomly cloning your project, and messing around with patching/testing it, then they don’t need to have jeweler installed.
The tasks
When you are ready to do a release, you first create the version. It is stored in VERSION (formerly VERSION.yml, but both work). This only updates what jeweler thinks the version is, and doesn’t actually release anything. It defaults to 0.0.0, but you can choose to specify your own:
rake version:write
rake version:write MAJOR=1 MINOR=5 PATCH=3
You’d typically release after this initial version created. Releasing involves generating a gemspec based on your version, and pushing it to GitHub, and tagging the release:
rake release
After your initial release, you can bump the version easily. You can choose to do the major, minor, or patch version. For 1.5.3, 1 is the major, 5 is the minor, and 3 is the patch:
rake version:bump:patch
rake version:bump:minor
rake version:bump:major
Version bumping only updates what version jeweler thinks you are using. You’ll need to do a release to actually release:
rake release
If you’ve configured your project for releasing to RubyForge, and you’ve registered your project, you can prepare RubyForge for it:
rake rubyforge:setup
Then you can release the docs and gem:
rake rubyforge:release
More resources
This has been a pretty high level overview and scant on details, so you might want to check out: