technicalpickles-jeweler 0.3.4 → 0.4.1

data/README.markdown

@@ -12,20 +12,16 @@ Trouble is when developing your Rubygems on GitHub, you generally do one of the
   * ... 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 intentions:
-
- * The only configuration should be providing a Gem::Specification to Jeweler
- * Version bumping should only be one command away
- * Authoritative version information should stored in one place
- * Jeweler should only concern itself with versioning and gems
- * Your Rakefile should be usable when Jeweler isn't installed (you just wouldn't be able to version bump or generate a gemspec)
- * Jeweler should use Jeweler. Oh the meta!
- 
-## Use Jeweler in a new project
+Jeweler was created with a few goals in mind:
 
-We'll use Jeweler as an example for creating a new project.
+ * 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!
 
-### Install it
+## Installation
 
 Run the following if you haven't already:
 
@@ -35,68 +31,118 @@ Install the gem:
 
     sudo gem install technicalpickles-jeweler
 
-### Create a directory and git repo
-
-    $ mkdir jeweler
-    $ cd jeweler
-    $ git init
+## Configuration for an existing project
 
-### Create a Rakefile:
+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:
 
-    require 'rake'
-    
     begin
-      require 'rubygems'
       require 'jeweler'
-      Jeweler.gemspec = Gem::Specification.new do |s|
-        s.name = "jeweler"
-        s.summary = "Simple and opinionated helper for creating Rubygem projects on GitHub"
+      Jeweler::Tasks.new do |s|
+        s.name = "the-perfect-gem"
+        s.summary = "TODO"
         s.email = "josh@technicalpickles.com"
-        s.homepage = "http://github.com/technicalpickles/jeweler"
-        s.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
-        s.authors = ["Josh Nichols", "Dan Croak"]
-        s.files =  FileList["[A-Z]*", "{generators,lib,test}/**/*"]
+        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.
 
-Note, we don't include 'date', or 'version'. Jeweler handles filing these in when it needs them.
+    $ 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.
 
-If you don't specify `s.files`, it will use `s.files = FileList["[A-Z]*.*", "{generators,lib,test,spec}/**/*"]`.
+With the repository firmly created, just push it:
 
-### Create a version file
+    $ 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.
 
-Create an initial `VERSION.yml`. It will by default to 0.0.0, but you can specify MAJOR, MINOR, and PATCH to tweak it:
+## Overview of Jeweler workflow
 
-    $ rake version:write MAJOR=1 MINOR=5 PATCH=2
-    (in /Users/nichoj/Projects/jeweler)
-    Wrote to VERSION.yml: 1.5.2
+Here's the general idea:
 
-### Generate the gemspec
+ * 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.
 
-    $ rake gemspec
-    
-This also validates that the gemspec should work on GitHub.
+### Versioning
 
-### Commit it already
+Versioning information is stored in `VERSION.yml`. It's a plain ol' YAML file which contains three things:
 
-    $ git add .
-    $ git commit -a -m "First commit, yo."
-    
-### Make a github repository
+ * major
+ * minor
+ * patch
+ 
+Consider, for a second, `1.5.3`.
+ 
+ * major = 1
+ * minor = 5
+ * patch = 3
 
-Wander to http://github.com/repositories/new and follow the instructions to get it pushed.
+#### Your first time
 
-### Enable RubyGem building on the repository
+When you first start using Jeweler, there won't be a `VERSION.yml`, so it'll assume 0.0.0.
 
-Go to your project's edit page and check the 'RubyGem' box.
+If you need some arbitrary version, you can do one of the following:
 
-### Implement something awesome
+ * `rake version:write MAJOR=6 MINOR=0 PATCH=3`
+ * Write `VERSION.yml` by hand (lame)
 
-I'll let you figure that out on your own.
 
-### Bump the version
+#### After that
 
 You have a few rake tasks for doing the version bump:
 
@@ -108,59 +154,30 @@ If you need to do an arbitrary bump, use the same task you used to create `VERSI
 
     $ rake version:write MAJOR=6 MINOR=0 PATCH=3
 
-After that, commit and push it:
+The process of version bumping does a commit to your repo, so make sure your repo is in a clean state (ie nothing uncommitted).
 
-    $ git commit -a -m "Version bump, yo."
-    $ git push origin master
+### Release it
 
-### Play the waiting game
+It's pretty straight forward:
 
-Wander over to [Has My Gem Built Yet](http://hasmygembuiltyet.org/) to play the waiting game.
+    $ rake release
+    
+This takes care of:
 
-## Extra stuff you might want to for your RubyGem project
+ * 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
 
-As was mentioned, Jeweler tries to only do versioning and gem stuff. Most projects have a few other needs:
+### Play the waiting game
 
- * Testing
- * RDoc
- * Default task
+How do you know when your gem is built? [Has My Gem Built Yet](http://hasmygembuiltyet.org/) was specifically designed to answer that question.
 
-Jeweler doesn't provide these. But it's easy enough to use Rake's built in tasks:
+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
 
-    require 'rake'
-    require 'rake/testtask'
-    require 'rake/rdoctask'
+### Putting it all together
 
-    begin
-      require 'rubygems'
-      require 'jeweler'
-      Jeweler.gemspec = Gem::Specification.new do |s|
-        s.name = "jeweler"
-        s.summary = "Simple and opinionated helper for creating Rubygem projects on GitHub"
-        s.email = "josh@technicalpickles.com"
-        s.homepage = "http://github.com/technicalpickles/jeweler"
-        s.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
-        s.authors = ["Josh Nichols", "Dan Croak"]
-        s.files =  FileList["[A-Z]*", "{generators,lib,test}/**/*"]
-      end
-    rescue LoadError
-      puts "Jeweler 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
-
-    desc 'Generate documentation for the safety_valve plugin.'
-    Rake::RDocTask.new(:rdoc) do |rdoc|
-      rdoc.rdoc_dir = 'rdoc'
-      rdoc.title    = 'Jeweler'
-      rdoc.options << '--line-numbers' << '--inline-source'
-      rdoc.rdoc_files.include('README.*')
-      rdoc.rdoc_files.include('lib/**/*.rb')
-    end
-
-    desc "Run the test suite"
-    task :default => :test
+    <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

@@ -15,7 +15,6 @@ begin
     gemspec.homepage = "http://github.com/technicalpickles/jeweler"
     gemspec.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
     gemspec.authors = ["Josh Nichols"]
-    gemspec.bindir = 'bin'
     gemspec.files =  FileList["[A-Z]*", "{bin,generators,lib,test}/**/*", 'lib/jeweler/templates/.gitignore']
     gemspec.add_dependency 'schacon-git'
   end
@@ -40,7 +39,7 @@ end
 
 Rcov::RcovTask.new do |t|
   t.libs << "test"
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/**/*_test.rb']
   t.verbose = true
 end
 

data/TODO

@@ -1,5 +1,7 @@
- * Generator for making new Jeweler projects
- * Rails generator for making a plugin that's Jeweler enabled
- * Git tagging/branching
- * Make sure everything is pushed/committed before bumping (controlled by a Jeweler.strict perhaps)
- * Have version:bump:xxx do a commit with an appropriate message 
+ * 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

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

data/lib/jeweler.rb

@@ -2,7 +2,6 @@ require 'date'
 
 require 'jeweler/bumping'
 require 'jeweler/versioning'
-require 'jeweler/singleton'
 require 'jeweler/gemspec'
 require 'jeweler/errors'
 require 'jeweler/generator'
@@ -12,7 +11,6 @@ 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::Singleton
   include Jeweler::Bumping
   include Jeweler::Versioning
   include Jeweler::Gemspec

data/lib/jeweler/bumping.rb

@@ -41,11 +41,21 @@ class Jeweler
         }
         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
+end

data/lib/jeweler/release.rb

@@ -12,15 +12,17 @@ class Jeweler
       @repo.commit("Regenerated gemspec for version #{version}")
       @repo.push
       
-#      require 'ruby-debug'
-#      breakpoint
-#      
-#      @repo.tag("v#{version}")
+      @repo.add_tag(release_tag)
+      @repo.push('origin', release_tag)
+    end
+
+    def release_tag
+      @release_tag ||= "v#{version}"
     end
     
   protected
     def any_pending_changes?
-      !@repo.status.added.empty? || !@repo.status.deleted.empty? || !@repo.status.changed.empty? || !@repo.status.untracked.empty?
+      @repo.status.added.empty? && @repo.status.deleted.empty? && @repo.status.changed.empty? && @repo.status.untracked.empty?
     end
   end
 end

data/lib/jeweler/tasks.rb

@@ -3,8 +3,10 @@ require 'rake/tasklib'
 
 class Jeweler
   class Tasks < ::Rake::TaskLib
-    def initialize(&block)
-      @gemspec = Gem::Specification.new(&block)
+    def initialize(gemspec = nil, &block)
+      @gemspec = Gem::Specification.new()
+      block.call(@gemspec) if block
+
       @jeweler = Jeweler.new(@gemspec)
       
       define_tasks
@@ -83,4 +85,4 @@ class Jeweler
       
     end
   end
-end
+end

data/lib/jeweler/templates/Rakefile

@@ -33,7 +33,7 @@ end
 
 Rcov::RcovTask.new do |t|
   t.libs << "test"
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/**/*_test.rb']
   t.verbose = true
 end
 

data/test/jeweler_test.rb

@@ -150,4 +150,4 @@ class JewelerTest < Test::Unit::TestCase
     end
   end
   
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: technicalpickles-jeweler
 version: !ruby/object:Gem::Version 
-  version: 0.3.4
+  version: 0.4.1
 platform: ruby
 authors: 
 - Josh Nichols
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-26 00:00:00 -07:00
+date: 2008-11-03 00:00:00 -08:00
 default_executable: jeweler
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,7 +41,6 @@ files:
 - lib/jeweler/gemspec.rb
 - lib/jeweler/generator.rb
 - lib/jeweler/release.rb
-- lib/jeweler/singleton.rb
 - lib/jeweler/tasks.rb
 - lib/jeweler/templates
 - lib/jeweler/templates/LICENSE

data/lib/jeweler/singleton.rb

@@ -1,22 +0,0 @@
-class Jeweler
-  module Singleton
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-    
-    module ClassMethods
-      # Gives Jeweler a gem to craft. This is really just a convience method for making the Rake usage nicer.
-      # In reality, this creates a new Jeweler, and assigns that to the singleton instance.
-      def craft(gemspec)
-        @@instance = new(gemspec)
-      end
-      alias_method :gemspec=, :craft
-
-      # Gets the current Jeweler. Typically only the Jeweler Rake tasks would use this. 
-      def instance
-        @@instance
-      end
-    end
-  end
-  
-end