technicalpickles-jeweler 0.0.6 → 0.0.7

data/README.markdown

@@ -1,13 +1,52 @@
-# Create a directory and git repo
+# 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 manage the gemspec, and deal with managing the version somehow
+  * ... 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 some simple goals:
+
+ * 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, a Version module in your project
+ * Jeweler should only concern itself with versioning and gems (and one day, git)
+ * 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
+
+We'll use Jeweler as an example for creating a new project.
+
+### Install it
+
+Run the following if you haven't already:
+
+    gem sources -a http://gems.github.com
+
+Install the gem:
+
+    sudo gem install technicalpickles-jeweler
+
+### Create a directory and git repo
 
     $ mkdir jeweler
+    $ cd jeweler
     $ git init
 
-# Create a Rakefile:
+### Create a Rakefile:
 
     require 'rake'
     
     begin
+      require 'rubygems'
       require 'jeweler'
       Jeweler.gemspec = Gem::Specification.new do |s|
         s.name = "jeweler"
@@ -22,14 +61,13 @@
       puts "Jeweler not available. Try installing technicalpickles-jeweler."
     end
 
+Note, we don't include 'date', or 'version'. Jeweler handles filing these in when it needs them.
 
-Note, we don't include 'date', or 'version'. Jeweler takes care of that.
-
-If you don't specify `s.files`, it will use `s.files = FileList["[A-Z]*", "{generators,lib,test,spec}/**/*"]`
+If you don't specify `s.files`, it will use `s.files = FileList["[A-Z]*", "{generators,lib,test,spec}/**/*"]`.
 
-For now, `s.name` should be lower-cased and underscored, without hyphens. That's because Jeweler camelizes and constantizes this value internally. For example, `ruby-debug` would be camelized/constanized to `Ruby-debug`, which isn't valid.
+For now, `s.name` should be lower-cased and underscored, without hyphens. That's because Jeweler camelizes and constantizes this value internally. For example, `ruby-debug` would be camelized/constanized to `Ruby-debug`, which isn't a valid constant. Use `ruby_debug` instead (for now).
 
-# Create a version file
+### Create a version file
 
 Stick it in `lib/(spec_name_here)/version.rb`, and start it out at some version, like 0.0.0:
 
@@ -51,40 +89,44 @@ OR
       end
     end
 
-Which you use depends on how you want to organize your gem. If you have a top-level class, like Jeweler, use the first. If you have a top level module, like Clearance, use the latter.
+Which you use depends on how you want to organize your gem. If you have a top-level class, like Jeweler, use the first. If you have a top level module, like ActiveRecord, use the latter.
 
-# Generate the first gemspec
+### Generate the gemspec
 
     $ rake gemspec
+    
+This also validates that the gemspec should work on GitHub.
 
-# Commit it
+### Commit it already
 
     $ git add .
-    $ git commit -a -m "First commit yo"
+    $ git commit -a -m "First commit, yo."
     
-# Make a github repository
+### Make a github repository
 
-Wander to http://github.com/repositories/new and follow the instructions to get it pushed
+Wander to http://github.com/repositories/new and follow the instructions to get it pushed.
 
-# Enable Rubygem building on the repository
+### Enable RubyGem building on the repository
 
 Go to your project's edit page and check the 'RubyGem' box.
 
-# Go do something awesome
+### Implement something awesome
 
-I'll let you figure that out
+I'll let you figure that out on your own.
 
-# Bump the version
+### Bump the version
 
-You have a few rake tasks for automating the version bumping:
+You have a few rake tasks for doing the version bump:
 
-    $ rake version:bump:patch
-    $ rake version:bump:minor
-    $ rake version:bump:major
-    
-This will automatically regenerate your gemspec.
+    $ 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
+
+After that, commit and push it:
+
+    $ git commit -a -m "Version bump, yo."
+    $ git push origin master
 
-Just commit and push it afterwards:
+### Play the waiting game
 
-    $ git commit -a -m "Version bump yo"
-    $ git push origin master
+Wander over to [Has My Gem Built Yet](http://hasmygembuiltyet.org/) to play the waiting game.

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rake'
 require 'rake/testtask'
+require 'rake/rdoctask'
 
 $:.unshift('lib')
 
@@ -23,6 +24,15 @@ Rake::TestTask.new do |t|
   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.markdown')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
  
 desc "Run the test suite"
 task :default => :test

data/TODO

@@ -2,5 +2,7 @@
   * ruby-debug -> Ruby::Debug
   * safety_valve -> SafetyValve
  * Generator for making new Jeweler projects
+ * Rails generator for making a plugin that's Jeweler enabled
  * Git tagging/branching
- * Release task
+ * 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 

data/lib/jeweler/bumping.rb

@@ -1,5 +1,8 @@
 class Jeweler
   module Bumping
+    # Bumps the patch version.
+    #
+    # 1.5.1 -> 1.5.2
     def bump_patch_version()
       patch = self.patch_version + 1
 
@@ -7,6 +10,9 @@ class Jeweler
       write_gemspec
     end
 
+    # Bumps the minor version.
+    #
+    # 1.5.1 -> 1.6.0
     def bump_minor_version()
       minor = minor_version + 1
 
@@ -14,6 +20,9 @@ class Jeweler
       write_gemspec
     end
 
+    # Bumps the major version.
+    #
+    # 1.5.1 -> 2.0.0
     def bump_major_version()
       major = major_version + 1
 
@@ -21,26 +30,29 @@ class Jeweler
       write_gemspec
     end
 
+    # Bumps the version, to the specific major/minor/patch version, writing out the appropriate version.rb, and then reloads it.
     def bump_version(major, minor, patch)
       main_module_or_class = constantize(main_module_name)
       keyword = top_level_keyword()
 
       File.open(version_module_path, 'w') do |file|
         file.write <<-END
-  #{keyword} #{main_module_name}
-    module Version
-      MAJOR = #{major}
-      MINOR = #{minor}
-      PATCH = #{patch}
-    end
+#{keyword} #{main_module_name}
+  module Version
+    MAJOR = #{major}
+    MINOR = #{minor}
+    PATCH = #{patch}
   end
-        END
+end
+END
       end
       @gemspec.version = "#{major}.#{minor}.#{patch}"
       refresh_version
     end
     
   protected
+    # Tries to figure out the Ruby keyword of what is containing the Version
+    # module. This should be 'module' or 'class', and is used for rewriting the version.rb.
     def top_level_keyword
       main_module_or_class = constantize(main_module_name)
       case main_module_or_class

data/lib/jeweler/errors.rb

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

data/lib/jeweler/gemspec.rb

@@ -1,16 +1,40 @@
 class Jeweler
   module Gemspec
+    # Generates a date for stuffing in the gemspec
     def date
       date = DateTime.now
       "#{date.year}-#{date.month}-#{date.day}"
     end
 
 
+    # Writes out the gemspec
     def write_gemspec
       @gemspec.date = self.date
       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
+        # Snippet borrowed from http://gist.github.com/16215
+        data = File.read(gemspec_path)
+      
+        spec = nil
+        if data !~ %r{!ruby/object:Gem::Specification}
+          Thread.new { spec = eval("$SAFE = 3\n#{data}", binding, gemspec_path) }.join
+        else
+          spec = YAML.load(data)
+        end
+        
+        puts "#{gemspec_path} is valid."
+      rescue Exception => e
+        puts "#{gemspec_path} is invalid. See the backtrace for more details."
+        raise
+      end
     end
     
   protected

data/lib/jeweler/singleton.rb

@@ -5,10 +5,14 @@ class Jeweler
     end
     
     module ClassMethods
-      def gemspec=(gemspec)
+      # 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

data/lib/jeweler/tasks.rb

@@ -1,6 +1,16 @@
-desc "Generate a gemspec file for GitHub"
-task :gemspec do
-  Jeweler.instance.write_gemspec
+desc "Generate and validates gemspec"
+task :gemspec => ['gemspec:generate', 'gemspec:validate']
+
+namespace :gemspec do
+  desc "Validates the gemspec"
+  task :validate do
+    Jeweler.instance.validate_gemspec
+  end
+  
+  desc "Generates the gemspec"
+  task :generate do
+    Jeweler.instance.write_gemspec
+  end
 end
 
 desc "Displays the current version"
@@ -10,11 +20,11 @@ end
 
 namespace :version do
   namespace :bump do
-    desc "Bump the gemspec a major version."
+    desc "Bump the gemspec by a major version."
     task :major do
       jeweler = Jeweler.instance
       
-      major = jeweler.major_version + 1
+      jeweler.bump_major_version
       
       jeweler.bump_version(major, 0, 0)
       jeweler.write_gemspec
@@ -22,14 +32,14 @@ namespace :version do
       puts "Version bumped to #{jeweler.version}"
     end
     
-    desc "Bump the gemspec a minor version."
+    desc "Bump the gemspec by a minor version."
     task :minor do
       jeweler = Jeweler.instance
       jeweler.bump_minor_version
       puts "Version bumped to #{jeweler.version}"
     end
     
-    desc "Bump the gemspec a patch version."
+    desc "Bump the gemspec by a patch version."
     task :patch do
       jeweler = Jeweler.instance
       jeweler.bump_patch_version

data/lib/jeweler/version.rb

@@ -1,7 +1,7 @@
-  class Jeweler
-    module Version
-      MAJOR = 0
-      MINOR = 0
-      PATCH = 6
-    end
+class Jeweler
+  module Version
+    MAJOR = 0
+    MINOR = 0
+    PATCH = 7
   end
+end

data/lib/jeweler/versioning.rb

@@ -1,17 +1,24 @@
 class Jeweler
   module Versioning
+    # Major version, as defined by the gemspec's Version module.
+    # For 1.5.3, this would return 1.
     def major_version
       version_module.const_get(:MAJOR)
     end
 
+    # Minor version, as defined by the gemspec's Version module.
+    # For 1.5.3, this would return 5.
     def minor_version
       version_module.const_get(:MINOR)
     end
 
+    # Patch version, as defined by the gemspec's Version module.
+    # For 1.5.3, this would return 5.
     def patch_version
       version_module.const_get(:PATCH)
     end
 
+    # Human readable version, which is used in the gemspec.
     def version
       "#{major_version}.#{minor_version}.#{patch_version}"
     end
@@ -25,12 +32,13 @@ class Jeweler
       constantize("#{main_module_name}::Version")
     end
   
+    # 
     def refresh_version
-      # Remove the constants, so we can reload the version_module
       undefine_versions()
       load_version()
     end
 
+    # Undefines version constants, so we can +load+ the version.rb again.
     def undefine_versions
       version_module.module_eval do
         remove_const(:MAJOR) if const_defined?(:MAJOR)
@@ -40,7 +48,7 @@ class Jeweler
     end
 
     def load_version
-      load version_module_path
+      load(version_module_path)
     end
   end
 end

data/lib/jeweler.rb

@@ -4,10 +4,12 @@ require 'jeweler/bumping'
 require 'jeweler/versioning'
 require 'jeweler/singleton'
 require 'jeweler/gemspec'
+require 'jeweler/errors'
 
 require 'jeweler/tasks' if defined?(Rake)
 require 'jeweler/active_support' # Adds the stolen camelize and constantize
 
+# 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
@@ -18,6 +20,7 @@ class Jeweler
   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
     

data/test/jeweler_test.rb

@@ -56,7 +56,7 @@ end
     end
   end
   
-  context 'A gem, with top level module,' do
+  context 'A jeweler (with a gemspec with top level module)' do
     setup do
       write_version_file('foo', 'module', 'Foo', 0, 1, 0)
       @spec = Gem::Specification.new do |s|
@@ -129,7 +129,7 @@ end
     
   end
   
-  context "A gem, with top level class," do
+  context "A Jeweler (with a gemspec with top level class)" do
     setup do
       write_version_file('bar', 'class', 'Bar', 1, 5, 2)
       
@@ -171,4 +171,10 @@ end
     end
   end
   
+  should "raise an exception when created with a nil gemspec" do
+    assert_raises Jeweler::GemspecError do
+      @jeweler = Jeweler.new(nil, File.dirname(__FILE__))
+    end
+  end
+  
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: technicalpickles-jeweler
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors: 
 - Josh Nichols
@@ -29,6 +29,7 @@ files:
 - lib/jeweler
 - lib/jeweler/active_support.rb
 - lib/jeweler/bumping.rb
+- lib/jeweler/errors.rb
 - lib/jeweler/gemspec.rb
 - lib/jeweler/singleton.rb
 - lib/jeweler/tasks.rb