namelessjon-jeweler 0.5.0

data/README.markdown

@@ -0,0 +1,183 @@
+# Jeweler: Let us craft you the perfect gem
+
+Rubygems are the awesome way of distributing your code to others. GitHub is the awesome way of managing the source code of your project. GitHub can even generate a Rubygem if you include a gemspec.
+
+Trouble is when developing your Rubygems on GitHub, you generally do one of the following:
+
+ * Manage the gemspec by hand
+  * ... why bother doing something by hand when you can automate it?
+ * Write your own Rake stuff to create the Gem::Specification and output it to a gemspec file, and deal with keeping the Rakefile and gemspec in sync
+  * ... why keep reinventing the wheel?
+ * Use hoe or echoe for generating the gemspec
+  * ... why use utilities made for the days before GitHub existed?
+  * ... why have extra stuff you aren't going to use?
+
+Jeweler was created with a few goals in mind:
+
+ * Only use a Gem::Specification as configuration
+ * Be one command away from version bumping and releasing
+ * Store version information in one place
+ * Only concern itself with git, gems, and versioning
+ * Not be a requirement for using your Rakefile (you just wouldn't be able to use its tasks)
+ * Use Jeweler internally. Oh the meta!
+
+## Installation
+
+Run the following if you haven't already:
+
+    gem sources -a http://gems.github.com
+
+Install the gem:
+
+    sudo gem install technicalpickles-jeweler
+
+## Configuration for an existing project
+
+Armed with the gem, we can begin diving into an example. [the-perfect-gem](http://github.com/technicalpickles/the-perfect-gem/tree) was setup as a Jeweler showcase, and a simple example:
+
+    begin
+      require 'jeweler'
+      Jeweler::Tasks.new do |s|
+        s.name = "the-perfect-gem"
+        s.summary = "TODO"
+        s.email = "josh@technicalpickles.com"
+        s.homepage = "http://github.com/technicalpickles/the-perfect-gem"
+        s.description = "TODO"
+        s.authors = ["Josh Nichols"]
+      end
+    rescue LoadError
+      puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+    end
+
+Here's a rundown of what's happening:
+
+ * Wrap everything in a begin block, and rescue from LoadError
+  * This lets us degrade gracefully if jeweler isn't installed
+ * Make a new `Jeweler::Tasks`
+   * It gets yielded a new `Gem::Specification`
+   * This is where all the configuration happens
+    * Things you definitely need to specify:
+      * `name`
+    * Things you probably want to specify:
+      * `summary`
+      * `email`
+      * `homepage`
+      * `description`
+      * `authors`
+    * Things you can specify, but have defaults
+     * `files`, defaults to `FileList["[A-Z]*.*", "{bin,generators,lib,test,spec}/**/*"]`
+    * Things you shouldn't specify:
+     * `version`, because Jeweler takes care of this for you
+    * Other things of interest
+     * `executables`, if you have any scripts
+     * `add_dependency`, if you have any dependencies
+    * Keep in mind that this is a `Gem::Specification`, so you can do whatever you would need to do to get your gem in shape
+
+## Bootstrap a new project
+
+Before proceeding, take a minute to setup your git environment, specifically your name and email address:
+
+    $ git config --global user.email johndoe@example.com
+    $ git config --global user.name 'John Doe'
+
+Jeweler provides a generator of sorts, `jeweler`. It takes two arguments: your GitHub username and a repository name.
+
+    $ jeweler technicalpickles the-perfect-gem
+
+Basically, this does:
+
+ * Creates the the-perfect-gem directory
+ * Seeds it with some basic files:
+  * `.gitignore`, with the usual suspects predefined
+  * `Rakefile`, setup with tasks for jeweler, test, rdoc, and rcov
+  * `README`, with your project name
+  * `LICENSE`, MIT, with your name prefilled
+  * `test/test_helper`, setup with shoulda, mocha, and a re-opened `Test::Unit::TestCase`
+  * `test/the_perfect_gem.rb`, placeholder failing test
+  * `lib/the_perfect_gem.rb`, placeholder library file
+ * Makes it a git repo
+ * Sets up `git@github.com:technicalpickles/jeweler.git` as the `origin` git remote
+ * Makes an initial commit, but does not push
+
+At this point, you probably should create a repository by wandering to [http://github.com/repositories/new](http://github.com/repositories/new). Be sure to use the same project name you told Jeweler.
+
+With the repository firmly created, just push it:
+
+    $ git push origin master
+
+You also probably should [enable RubyGem creation for you repository](http://github.com/blog/51-github-s-rubygem-server): Go to your project's edit page and check the 'RubyGem' box.
+
+## Overview of Jeweler workflow
+
+Here's the general idea:
+
+ * Hack, commit, hack, commit, etc, etc
+ * Version bump
+ * Release
+ * Have a delicious scotch
+
+The hacking and the scotch are up to you, but Jeweler provides rake tasks for the rest.
+
+### Versioning
+
+Versioning information is stored in `VERSION.yml`. It's a plain ol' YAML file which contains three things:
+
+ * major
+ * minor
+ * patch
+
+Consider, for a second, `1.5.3`.
+
+ * major = 1
+ * minor = 5
+ * patch = 3
+
+#### Your first time
+
+When you first start using Jeweler, there won't be a `VERSION.yml`, so it'll assume 0.0.0.
+
+If you need some arbitrary version, you can do one of the following:
+
+ * `rake version:write MAJOR=6 MINOR=0 PATCH=3`
+ * Write `VERSION.yml` by hand (lame)
+
+
+#### After that
+
+You have a few rake tasks for doing the version bump:
+
+    $ rake version:bump:patch # 1.5.1 -> 1.5.2
+    $ rake version:bump:minor # 1.5.1 -> 1.6.0
+    $ rake version:bump:major # 1.5.1 -> 2.0.0
+
+If you need to do an arbitrary bump, use the same task you used to create `VERSION.yml`:
+
+    $ rake version:write MAJOR=6 MINOR=0 PATCH=3
+
+The process of version bumping does a commit to your repo, so make sure your repo is in a clean state (ie nothing uncommitted).
+
+### Release it
+
+It's pretty straight forward:
+
+    $ rake release
+
+This takes care of:
+
+ * Generating a `.gemspec` for you project, with the version you just bumped to
+ * Commit and push the updated `.gemspec`
+ * Create a tag
+ * Push the tag
+
+### Play the waiting game
+
+How do you know when your gem is built? [Has My Gem Built Yet](http://hasmygembuiltyet.org/) was specifically designed to answer that question.
+
+If it happens to be down, you can also check out the GitHub Gem repo's [list](http://gems.github.com/list). Just search for youname-yourrepo.s
+
+### Putting it all together
+
+    <hack, hack, hack, commit>
+    $ rake version:bump:patch release
+
+Now browse to http://gems.github.com/yourname/yourproject, and wait for it to be built.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rcov/rcovtask'
+
+$:.unshift('lib')
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "jeweler"
+    gemspec.executables = "jeweler"
+    gemspec.summary = "Simple and opinionated helper for creating Rubygem projects on GitHub"
+    gemspec.email = "josh@technicalpickles.com"
+    gemspec.homepage = "http://github.com/technicalpickles/jeweler"
+    gemspec.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
+    gemspec.authors = ["Josh Nichols"]
+    gemspec.files =  FileList["[A-Z]*", "{bin,generators,lib,test}/**/*", 'lib/jeweler/templates/.gitignore']
+    gemspec.add_dependency 'schacon-git'
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'jeweler'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.markdown')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Rcov::RcovTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :rcov

data/TODO

@@ -0,0 +1,7 @@
+ * Generators
+   * Rails generator for making a plugin that's Jeweler enabled
+   * Support rspec?
+ * Releasing
+  * Create tag based on version
+  * Push tags
+  * Open hasmygembuiltyet.org

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+patch: 0
+major: 0
+minor: 5

data/bin/jeweler

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'optparse'
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'jeweler'
+
+class JewelerOpts < Hash
+  attr_reader :opts
+  def initialize(args)
+    super()
+    self[:spec] = false
+    @opts = OptionParser.new do |o|
+      o.banner = "Usage: #{File.basename($0)} [options] reponame\ne.g. #{File.basename($0)} the-perfect-gem"
+      o.on('-s','--spec', 'use bacon to generate specs') do
+        self[:spec] = true
+      end
+      o.on_tail('-h', '--help', 'display this help and exit') do
+        puts o
+        exit
+      end
+    end
+    @opts.parse!(args)
+  end
+end
+
+o = JewelerOpts.new(ARGV)
+
+unless ARGV.size == 1
+  puts o.opts
+  exit 1
+end
+
+github_repo_name = ARGV.first
+generator = Jeweler::Generator.new github_repo_name
+generator.spec = o[:spec]
+generator.run

data/lib/jeweler.rb

@@ -0,0 +1,34 @@
+require 'date'
+
+require 'jeweler/bumping'
+require 'jeweler/versioning'
+require 'jeweler/gemspec'
+require 'jeweler/errors'
+require 'jeweler/generator'
+require 'jeweler/release'
+
+require 'jeweler/tasks'
+
+# A Jeweler helps you craft the perfect Rubygem. Give him a gemspec, and he takes care of the rest.
+class Jeweler
+  include Jeweler::Bumping
+  include Jeweler::Versioning
+  include Jeweler::Gemspec
+  include Jeweler::Release
+
+  attr_reader :gemspec
+  attr_accessor :base_dir
+
+  def initialize(gemspec, base_dir = '.')
+    raise(GemspecError, "Can't create a Jeweler with a nil gemspec") if gemspec.nil?
+    @gemspec = gemspec
+    @base_dir = base_dir
+
+    @gemspec.files ||= FileList["[A-Z]*.*", "{bin,generators,lib,test,spec}/**/*"]
+
+    if File.exists?(File.join(base_dir, '.git'))
+      @repo = Git.open(base_dir)
+    end
+  end
+end
+

data/lib/jeweler/bumping.rb

@@ -0,0 +1,61 @@
+class Jeweler
+  module Bumping
+    # Bumps the patch version.
+    #
+    # 1.5.1 -> 1.5.2
+    def bump_patch_version()
+      patch = self.patch_version.to_i + 1
+
+      write_version(major_version, minor_version, patch)
+    end
+
+    # Bumps the minor version.
+    #
+    # 1.5.1 -> 1.6.0
+    def bump_minor_version()
+      minor = minor_version.to_i + 1
+
+      write_version(major_version, minor)
+    end
+
+    # Bumps the major version.
+    #
+    # 1.5.1 -> 2.0.0
+    def bump_major_version()
+      major = major_version.to_i + 1
+
+      write_version(major)
+    end
+
+    # Bumps the version, to the specific major/minor/patch version, writing out the appropriate version.rb, and then reloads it.
+    def write_version(major = 0, minor = 0, patch = 0)
+      major ||= 0
+      minor ||= 0
+      patch ||= 0
+
+      File.open(version_yaml_path, 'w+') do |f|
+        version_hash = {
+          'major' => major.to_i,
+          'minor' => minor.to_i,
+          'patch' => patch.to_i
+        }
+        YAML.dump(version_hash, f)
+      end
+
+      refresh_version
+
+      @gemspec.version = version
+
+      puts "Wrote to #{version_yaml_path}: #{version}"
+
+      commit_version
+    end
+
+    def commit_version
+      if @repo
+        @repo.add('VERSION.yml')
+        @repo.commit("Version bump to #{version}", 'VERSION.yml')
+      end
+    end
+  end
+end

data/lib/jeweler/errors.rb

@@ -0,0 +1,8 @@
+class Jeweler
+  # Gemspec related error
+   class GemspecError < StandardError
+   end
+
+   class VersionYmlError < StandardError
+   end
+end

data/lib/jeweler/gemspec.rb

@@ -0,0 +1,48 @@
+class Jeweler
+  module Gemspec
+    # Writes out the gemspec
+    def write_gemspec
+      self.refresh_version
+      @gemspec.version = self.version
+      @gemspec.date = Time.now
+      File.open(gemspec_path, 'w') do |f|
+        f.write @gemspec.to_ruby
+      end
+      puts "Generated: #{gemspec_path}"
+    end
+
+    # Validates the gemspec in an environment similar to how GitHub would build
+    # it. See http://gist.github.com/16215
+    def validate_gemspec
+      begin
+        parse_gemspec
+        puts "#{gemspec_path} is valid."
+      rescue Exception => e
+        puts "#{gemspec_path} is invalid. See the backtrace for more details."
+        raise
+      end
+    end
+
+
+    def valid_gemspec?
+      begin
+        parse_gemspec
+        true
+      rescue Exception => e
+        false
+      end
+    end
+
+    def parse_gemspec(data = nil)
+      data ||= File.read(gemspec_path)
+      Thread.new { eval("$SAFE = 3\n#{data}", binding, gemspec_path) }.join
+    end
+
+  protected
+    def gemspec_path
+      denormalized_path = File.join(@base_dir, "#{@gemspec.name}.gemspec")
+      absolute_path = File.expand_path(denormalized_path)
+      absolute_path.gsub(Dir.getwd + File::SEPARATOR, '')
+    end
+  end
+end

data/lib/jeweler/generator.rb

@@ -0,0 +1,124 @@
+require 'git'
+require 'erb'
+
+class Jeweler
+  class NoGitUserName < StandardError
+  end
+  class NoGitUserEmail < StandardError
+  end
+  class FileInTheWay < StandardError
+  end
+  class NoGitHubRepoNameGiven < StandardError
+  end
+  class NoGitHubUser < StandardError
+  end
+
+  class Generator
+    attr_accessor :target_dir, :user_name, :user_email,
+                  :github_repo_name, :github_remote, :github_url, :github_username,
+                  :lib_dir, :constant_name, :file_name_prefix, :config, :spec
+
+    def initialize(github_repo_name, dir = nil)
+      check_user_git_config()
+
+      if github_repo_name.nil?
+        raise NoGitHubRepoNameGiven
+      end
+      self.github_repo_name = github_repo_name
+
+      self.github_remote = "git@github.com:#{github_username}/#{github_repo_name}.git"
+      self.github_url = "http://github.com/#{github_username}/#{github_repo_name}"
+
+
+      self.target_dir = dir || self.github_repo_name
+      self.lib_dir = File.join(target_dir, 'lib')
+      self.constant_name = self.github_repo_name.split(/[-_]/).collect{|each| each.capitalize }.join
+      self.file_name_prefix = self.github_repo_name.gsub('-', '_')
+    end
+
+    def run
+      create_files
+      gitify
+    end
+
+    def testspec
+      if self.spec
+        'spec'
+      else
+        'test'
+      end
+    end
+
+    def test_dir
+      File.join(target_dir, testspec)
+    end
+
+
+  private
+    def create_files
+      begin
+        FileUtils.mkdir target_dir
+      rescue Errno::EEXIST => e
+        puts "The directory #{target_dir} already exists, aborting. Maybe move it out of the way before continuing?"
+        exit 1
+      end
+
+      FileUtils.mkdir lib_dir
+      FileUtils.mkdir test_dir
+
+      output_template_in_target('.gitignore')
+      output_template_in_target('Rakefile')
+      output_template_in_target('LICENSE')
+      output_template_in_target('README')
+      output_template_in_target("#{testspec}/#{testspec}_helper.rb")
+      output_template_in_target("#{testspec}/flunking_#{testspec}.rb", "#{testspec}/#{file_name_prefix}_#{testspec}.rb")
+
+      FileUtils.touch File.join(lib_dir, "#{file_name_prefix}.rb")
+    end
+
+    def check_user_git_config
+      self.config = read_git_config
+      unless config.has_key? 'user.name'
+        raise NoGitUserName, %Q{No user.name set in ~/.gitconfig. Set it with: git config --global user.name 'Your Name Here'}
+      end
+      unless config.has_key? 'user.email'
+        raise NoGitUserEmail, %Q{No user.name set in ~/.gitconfig. Set it with: git config --global user.name 'Your Name Here'}
+      end
+      unless config.has_key? 'github.user'
+        raise NoGitHubUser, %Q{No github.user set in ~/.gitconfig. Set it with: git config --global github.user 'Your username here'}
+      end
+
+      self.user_name = config['user.name']
+      self.user_email = config['user.email']
+      self.github_username = config['github.user']
+    end
+
+    def output_template_in_target(source, destination = source)
+      template = ERB.new(File.read(File.join(File.dirname(__FILE__), 'templates', source)))
+      File.open(File.join(target_dir, destination), 'w') {|file| file.write(template.result(binding))}
+    end
+
+    def gitify
+      saved_pwd = Dir.pwd
+      Dir.chdir(target_dir)
+      begin
+        repo = Git.init()
+        repo.add('.')
+        repo.commit "Initial commit to #{github_repo_name}."
+        repo.add_remote('origin', github_remote)
+      rescue Git::GitExecuteError => e
+        puts "Encountered an error during gitification. Maybe the repo already exists, or has already been pushed to?"
+        puts
+        raise
+      end
+      Dir.chdir(saved_pwd)
+    end
+
+    def read_git_config
+      # we could just use Git::Base's .config, but that relies on a repo being around already
+      # ... which we don't have yet, since this is part of a sanity check
+      lib = Git::Lib.new(nil, nil)
+      config = lib.parse_config '~/.gitconfig'
+    end
+  end
+end