It's crucial to understand the gem object is just a Gem::Specification. You can read up about it at docs.rubygems.org/read/chapter/20. This is the most basic way of specifying a gem, Jeweler-managed or not. Jeweler just exposes this to you, in addition to providing some reasonable defaults, which we'll explore now.

Project information

gem.name = "whatwhatwhat"

Every gem has a name. Among other things, the gem name is how you are able to gem install it. Reference

gem.summary = %Q{TODO: one-line summary of your gem}

This is a one line summary of your gem. This is displayed, for example, when you use gem list --details or view it on rubygems.org.

gem.description = %Q{TODO: longer description of your gem}

Description is a longer description. Scholars ascertain that knowledge of where the description is used was lost centuries ago.

gem.email = "josh@technicalpickles.com"

This should be a way to get a hold of you regarding the gem.

gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"

The homepage should have more information about your gem. The jeweler generator guesses this based on the assumption your code lives on GitHub, using your Git configuration to find your GitHub username. This is displayed by gem list --details and on rubygems.org.

gem.authors = ["Joshua Nichols"]

Hey, this is you, the author (or me in this case). The jeweler generator also guesses this from your Git configuration. This is displayed by gem list --details and on rubygems.org.

Files

The quickest way to add more files is to git add them. Jeweler uses your Git repository to populate your gem's files by including added and committed and excluding .gitignored. In most cases, this is reasonable enough.

If you need to tweak the files, that's cool. Jeweler populates gem.files as a Rake::FileList. It's like a normal array, except you can include and exclude file globs:

Dependencies

Dependencies let you define other gems that your gem needs to function. gem install your-gem will install your-gem's dependencies along with it, and when you use your-gem in an application, the dependencies will be made available. Use gem.add_dependency to register them. Reference

gem.add_dependency 'nokogiri'

This will ensure a version of nokogiri is installed, but it doesn't require anything more than that. You can provide extra args to be more specific:

When specifying which version is required, there's a bit of the condunrum. You want to allow the most versions possible, but you want to be sure they are compatible. Using >= 1.2.1 is fine most of the time, except until the point that 2.0.0 comes out and totally breaks backwards the API. That's when it's good to use ~> 1.2.1, which requires any version in the 1.2 family, starting with 1.2.1.

Executables

Executables let your gem install shell commands. Just put any executable scripts in the bin/ directory, make sure they are added using git, and Jeweler will take care of the rest.

When you need more finely grained control over it, you can set it yourself:

gem.executables = ['foo'] # note, it's the file name relative to `bin/`, not the project root

Versioning

We discussed earlier how to bump the version. The rake tasks are really just convience methods for manipulating the VERSION file. It just contains a version string, like 1.2.3.

VERSION is a convention used by Jeweler, and is used to populate gem.version. You can actually set this yourself, and Jeweler won't try to override it:

gem.version = '1.2.3'

A common pattern is to have this in a version constant in your library. This is convenient, because users of the library can query the version they are using at runtime.

Rake tasks

Jeweler lives inside of Rake. As a result, they are dear friends. But, that friendship doesn't interfere with typical Rake operations.

That means you can define your own namespaces, tasks, or use third party Rake libraries without cause for concern.

Contributing to Jeweler

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

Ask on the mailing list for feedback on your proposal, to see if somebody else has done it.

Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

Fork the project

Start a feature/bugfix branch

Commit and push until you are happy with your contribution

Make sure to add tests for the feature/bugfix. This is important so I don't break it in a future version unintentionally.

Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate it to its own commit so I can cherry-pick around it.