hoe 2.4.0 → 2.5.0

data/.autotest

@@ -3,5 +3,5 @@
 require 'autotest/restart'
 
 Autotest.add_hook :initialize do |at|
-  at.testlib = "minitest/unit" # FIX: autotest testlib sucks
+  at.testlib = "minitest/unit"
 end

data/History.txt

@@ -1,3 +1,21 @@
+=== 2.5.0 / 2010-01-06
+
+* 8 minor enhancements:
+
+  * Add extra dirs to rcov include path if needed.
+  * Added Hoe#dependency_target to make dependencies easier to declare.
+  * Added extra doco to describe how auto-population works.
+  * Added more doco to readme.
+  * Don't bother posting news to rubyforge.
+  * Hoe::Inline plugin now deals with X::Y by flattening the name.
+  * Merged some of Hoe.pdf to README.txt and further improved doco.
+  * Pushed gemcutter & rubyforge dependencies down to the plugins.
+
+* 2 bug fixes:
+
+  * Fix perms on Hoe.pdf after copying.
+  * Fixed Hoe rdoc problem caused by gemcutter plugin.
+
 === 2.4.0 / 2009-12-08
 
 * 6 minor enhancements:

data/README.txt

@@ -7,15 +7,16 @@
 
 == DESCRIPTION:
 
-Hoe is a rake/rubygems helper for project Rakefiles. It helps generate
-rubygems and includes a dynamic plug-in system allowing for easy
-extensibility. Hoe ships with plug-ins for all your usual project
-tasks including rdoc generation, testing, packaging, and deployment.
+Hoe is a rake/rubygems helper for project Rakefiles. It helps you
+manage and maintain, and release your project and includes a dynamic
+plug-in system allowing for easy extensibility. Hoe ships with
+plug-ins for all your usual project tasks including rdoc generation,
+testing, packaging, and deployment.
 
 See class rdoc for help. Hint: `ri Hoe` or any of the plugins listed
 below.
 
-See Also: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
+For extra goodness, see: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
 
 == FEATURES/PROBLEMS:
 
@@ -26,6 +27,126 @@ See Also: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
 * Sow uses a simple ERB templating system allowing you to capture your
   project patterns.
 
+== SYNOPSIS:
+
+  % sow [group] project
+
+(you can edit a project template in ~/.hoe_template after running sow
+for the first time)
+
+or:
+
+  require 'hoe'
+  
+  Hoe.spec projectname do
+    # ... project specific data ...
+  end
+
+  # ... project specific tasks ...
+
+== Deployment, the DRY way
+
+Hoe focuses on keeping everything in its place in a useful form and
+intelligently extracting what it needs. As a result, there are no
+extra YAML files, config directories, ruby files, or any other
+artifacts in your release that you wouldn't already have.
+
+=== Structure Overview
+
+  project_dir/
+    History.txt
+    Manifest.txt
+    README.txt
+    Rakefile
+    bin/...
+    lib/...
+    test/...
+
+=== README.txt
+
+Most projects have a readme file of some kind that describes the
+project. Hoe projects are no different, but we take them one step
+further. The readme file points the reader towards all the information
+they need to know to get started including a description, relevant
+urls, code synopsis, license, etc. Hoe knows how to read a basic rdoc
+formatted file to pull out the description (and summary by extension),
+urls, and extra paragraphs of info you may want to provide in
+news/blog posts.
+
+=== History.txt
+
+Every project should have a document describing changes over time. Hoe
+can read this file (also in rdoc) and include the latest changes in
+your announcements.
+
+=== Manifest.txt
+
+<em><strong>manifest [noun]</strong> a document giving comprehensive
+details of a ship and its cargo and other contents, passengers, and
+crew for the use of customs officers.</em>
+
+Every project should know what it is shipping. This is done via an
+explicit list of everything that goes out in a release. Hoe uses this
+during packaging so that nothing embarrassing is picked up.
+          
+Imagine, you're a customs inspector at the Los Angeles Port, the
+world's largest import/export port. A large ship filled to the brim
+pulls up to the pier ready for inspection. You walk up to the captain
+and his crew and ask "what is the contents of this fine ship today"
+and the captain answers "oh... whatever is inside". The mind boggles.
+There is no way in the world that a professionally run ship would ever
+run this way and there is no way that you should either.
+
+Professional software releases know _exactly_ what is in them, amateur
+releases _do not_. "Write better globs" is the response I often hear.
+I consider myself and the people I work with to be rather smart people
+and if we get them wrong, chances are you will too. How many times
+have you peered under the covers and seen .DS_Store, emacs backup~
+files, vim vm files and other files completely unrelated to the
+package? I have far more times than I'd like.
+
+=== VERSION
+
+Releases have versions and I've found it best for the version to be
+part of the code. You can use this during runtime in a multitude of
+ways. Hoe finds your version and uses it automatically during
+packaging.
+
+=== Releasing in 1 easy step
+      
+  % rake release VERSION=x.y.z
+      
+That really is all there is to it. Behind the scenes it:
+
+* Branches the release in our perforce server. (via hoe-seattlerb plugin)
+* Performs sanity checks to ensure the release has integrity. (hoe-seattlerb)
+* Packages into gem and tarballs.
+* Uploads the packages to rubyforge.
+* Posts news of the release to rubyforge and my blog.
+* Sends an announcement email. (hoe-seattlerb)
+      
+That `VERSION=x.y.z` is there as a last-chance sanity check that you
+know what you're releasing. You'd be surprised how blurry eyed/brained
+you get at 3AM. This check helps a lot more than it should.
+
+== Plugins:
+
+Hoe has a flexible plugin system that allows you to activate and
+deactivate what tasks are available on a given project. Hoe has been
+broken up into plugins partially to make maintenance easier but also
+to make it easier to turn off or replace code you don't want.
+
+* To activate a plugin, add the following to your Rakefile above your
+  Hoe spec:
+
+    Hoe.plugin :plugin_name
+
+* To deactivate a plugin, remove its name from the plugins array:
+
+    Hoe.plugins.delete :plugin_name
+
+Again, this must be done before the Hoe spec, or it won't be useful.
+
 === Plug-ins Provided:
 
 * Hoe::Clean
@@ -33,6 +154,7 @@ See Also: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
 * Hoe::Deps
 * Hoe::Flay
 * Hoe::Flog
+* Hoe::Gemcutter
 * Hoe::Inline
 * Hoe::Newb
 * Hoe::Package
@@ -44,27 +166,100 @@ See Also: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
 
 === Known 3rd-Party Plugins:
 
-* Hoe::Seattlerb - email announcements & perforce branching/validation on release.
+* Hoe::Seattlerb - minitest support, email announcements & perforce branching/validation on release.
 * Hoe::Git       - git tagging on release, changelogs, and manifest creation.
 * Hoe::Doofus    - release checklist.
 * Hoe::Debugging - for extensions, run your tests with GDB and Valgrind
 
-== SYNOPSIS:
+=== Writing Plugins:
 
-  % sow [group] project
+A plugin can be as simple as:
+      
+    module Hoe::Thingy
+      attr_accessor :thingy
 
-(you can edit a project template in ~/.hoe_template after running sow
-for the first time)
+      def initialize_thingy # optional
+        self.thingy = 42
+      end
 
-or:
+      def define_thingy_tasks
+        task :thingy do
+          puts thingy
+        end
+      end
+    end
+      
+Not terribly useful, but you get the idea. This example exercises both
+plugin methods (initialize_#{plugin} and define_#{plugin}_tasks and
+adds an accessor method to the Hoe instance.
 
-  require 'hoe'
-  
-  Hoe.spec projectname do
-    # ... project specific data ...
-  end
+=== How Plugins Work
 
-  # ... project specific tasks ...
+Hoe plugins are made to be as simple as possible, but no simpler. They are
+modules defined in the `Hoe` namespace and have only one required method
+(`define_#{plugin}_tasks`) and one optional method (`initialize_#{plugin}`).
+Plugins can also define their own methods and they'll be available as instance
+methods to your hoe-spec. Plugins have 4 simple phases:
+
+==== Loading
+
+When Hoe is loaded the last thing it does is to ask rubygems for all of its
+plugins. Plugins are found by finding all files matching "hoe/*.rb" via
+installed gems or `$LOAD_PATH`. All found files are then loaded.
+
+==== Activation
+
+All of the plugins that ship with hoe are activated by default. This is
+because they're providing the same functionality that the previous Hoe was and
+without them, it'd be rather useless. Other plugins should be "opt-in" and are
+activated by:
+          
+    Hoe::plugin :thingy
+          
+Put this _above_ your hoe-spec. All it does is add `:thingy` to `Hoe.plugins`.
+You could also deactivate a plugin by removing it from `Hoe.plugins` although
+that shouldn't be necessary for the most part.
+          
+Please note that it is **not** a good idea to have a plugin you're writing
+activate itself. Let developers opt-in, not opt-out. Just because someone
+needs the `:thingy` plugin on one project doesn't mean they need them on _all_
+their projects.
+
+==== Initialization
+
+When your hoe-spec is instantiated, it extends itself all known plugin
+modules. This adds the method bodies to the hoe-spec and allows for the plugin
+to work as part of the spec itself. Once that is over, activated plugins have
+their **optional** define `initialize_#{plugin}` methods called. This lets
+them set needed instance variables to default values. Finally, the hoe-spec
+block is evaluated so that project specific values can override the defaults.
+
+==== Task Definition
+
+Finally, once the user's hoe-spec has been evaluated, all activated plugins
+have their `define_#{plugin}_tasks` method called. This method must be defined
+and it is here that you'll define all your tasks.
+
+== HOW TO CONTRIBUTE OR GET SUPPORT:
+
+=== Mailing List
+
+A mailing list for hoe is hosted at: http://rubyforge.org/projects/seattlerb
+
+=== Bugs & Feature Requests:
+
+We use the bug trackers hosted at: http://rubyforge.org/projects/seattlerb
+
+=== Patches:
+
+* If you have a bug fix or enhancement to hoe that you'd like to
+  contribute, please provide a unified diff and file it in a ticket in
+  the bug tracker listed above.
+* You can check out hoe:
+  * With git via github: http://github.com/seattlerb/hoe
+  * With svn via rubyforge: http://rubyforge.org/projects/seattlerb
+  * Or via perforce if you'd like to directly contribute:
+    http://www.zenspider.com/ZSS/Process/Perforce.html
 
 == REQUIREMENTS:
 

data/Rakefile

@@ -16,9 +16,15 @@ Hoe.spec "hoe" do
   pluggable!
 end
 
+task :plugins do
+  puts `find lib/hoe -name \*.rb | xargs grep -h module.Hoe::`.
+    gsub(/module/, '*')
+end
+
 [:redocs, :docs].each do |t|
   task t do
     cp "Hoe.pdf", "doc"
+    sh "chmod u+w doc/Hoe.pdf"
   end
 end
 

data/lib/hoe.rb

@@ -58,7 +58,7 @@ require 'hoe/rake'
 
 class Hoe
   # duh
-  VERSION = '2.4.0'
+  VERSION = '2.5.0'
 
   @@plugins = [:clean, :debug, :deps, :flay, :flog, :newb, :package,
                :publish, :rcov, :rubyforge, :gemcutter, :signing, :test]
@@ -97,12 +97,16 @@ class Hoe
   attr_accessor :author
 
   ##
-  # Optional: A description of the release's latest changes. Auto-populates.
+  # Optional: A description of the release's latest changes.
+  # Auto-populates to the top entry of History.txt.
 
   attr_accessor :changes
 
   ##
-  # Optional: A description of the project. Auto-populates.
+  # Optional: A description of the project. Auto-populates from the
+  # first paragraph of the DESCRIPTION section of README.txt.
+  #
+  # See also: Hoe#summary and Hoe.paragraphs_of.
 
   attr_accessor :description
 
@@ -180,7 +184,10 @@ class Hoe
   attr_accessor :spec_extras
 
   ##
-  # Optional: A short summary of the project. Auto-populates.
+  # Optional: A short summary of the project. Auto-populates from the
+  # first sentence of the description.
+  #
+  # See also: Hoe#description and Hoe.paragraphs_of.
 
   attr_accessor :summary
 
@@ -195,7 +202,9 @@ class Hoe
   attr_accessor :test_globs
 
   ##
-  # Optional: The url(s) of the project. (can be array). Auto-populates.
+  # Optional: The url(s) of the project. (can be array).
+  # Auto-populates to a list of urls read from the beginning of
+  # README.txt.
 
   attr_accessor :url
 
@@ -267,7 +276,13 @@ class Hoe
   end
 
   ##
-  # Create a new hoe-specification executing the supplied block
+  # Execute the Hoe DSL to define your project's Hoe specification
+  # (which interally creates a gem specification). All hoe attributes
+  # and methods are available within +block+. Eg:
+  #
+  #   Hoe.spec name do
+  #     # ... project specific data ...
+  #   end
 
   def self.spec name, &block
     Hoe.load_plugins
@@ -303,23 +318,26 @@ class Hoe
   # Add standard and user defined dependencies to the spec.
 
   def add_dependencies
-    hoe_deps = {
-      'rake'      => ">= #{RAKEVERSION}",
-      'rubyforge' => ">= #{::RubyForge::VERSION}", # TODO: push down
-    }
-
     self.extra_deps     = normalize_deps extra_deps
     self.extra_dev_deps = normalize_deps extra_dev_deps
 
-    if name == 'hoe' then
-      hoe_deps.each do |pkg, vers|
-        extra_deps << [pkg, vers]
-      end
+    case name
+    when 'hoe' then
+      extra_deps << ['rake', ">= #{RAKEVERSION}"]
+    when 'rubyforge', 'rake', 'gemcutter' then
+      # avoid circular dependencies for hoe's (potentially) hoe'd dependencies
     else
-      extra_dev_deps << ['hoe', ">= #{VERSION}"] unless hoe_deps.has_key? name
+      extra_dev_deps << ['hoe', ">= #{VERSION}"]
     end
   end
 
+  ##
+  # Returns the proper dependency list for the thingy.
+
+  def dependency_target
+    self.name == 'hoe' ? extra_deps : extra_dev_deps
+  end
+
   ##
   # Define the Gem::Specification.
 

data/lib/hoe/gemcutter.rb

@@ -1,20 +1,24 @@
 require 'rake'
+gem "gemcutter" # lame. gemcutter doesn't have a VERSION const.
 
-class Hoe #:nodoc:
-  module Gemcutter
-    def define_gemcutter_tasks
-      desc "Push gem to gemcutter."
-      task :release_to_gemcutter => [:clean, :package, :release_sanity] do
-        pkg   = "pkg/#{spec.name}-#{spec.version}"
-        gems  = Dir["#{pkg}*.gem"]
-        gems.each do |g|
-          # TODO - once gemcutter supports command invocation, use it.
-          # We could still fail here due to --format executable
-          sh Gem.ruby, "-S", "gem", "push", g
-        end
-      end
+module Hoe::Gemcutter
+  def initialize_gemcutter
+    version = Gem.loaded_specs['gemcutter'].version
+    dependency_target << ['gemcutter', ">= #{version}"]
+  end
 
-      task :release_to => :release_to_gemcutter
+  def define_gemcutter_tasks
+    desc "Push gem to gemcutter."
+    task :release_to_gemcutter => [:clean, :package, :release_sanity] do
+      pkg   = "pkg/#{spec.name}-#{spec.version}"
+      gems  = Dir["#{pkg}*.gem"]
+      gems.each do |g|
+        # TODO - once gemcutter supports command invocation, use it.
+        # We could still fail here due to --format executable
+        sh Gem.ruby, "-S", "gem", "push", g
+      end
     end
-  end unless defined? Gemcutter # HACK - tests force load twice
-end
+
+    task :release_to => :release_to_gemcutter
+  end
+end unless defined? Hoe::Gemcutter

data/lib/hoe/inline.rb

@@ -36,7 +36,7 @@ module Hoe::Inline
         dlext = Config::CONFIG['DLEXT']
 
         Inline.registered_inline_classes.each do |cls|
-          name = cls.name # TODO: what about X::Y::Z?
+          name = cls.name.gsub(/::/, '')
           # name of the extension is CamelCase
           alternate_name = if name =~ /[A-Z]/ then
                              name.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')

data/lib/hoe/publish.rb

@@ -100,7 +100,7 @@ module Hoe::Publish
         if title then
           rd.options << title
 
-          unless title =~ /=/ then # for ['-t', 'title here']
+          unless title =~ /\=/ then # for ['-t', 'title here']
             title_index = spec.rdoc_options.index(title)
             rd.options << spec.rdoc_options[title_index + 1]
           end
@@ -119,7 +119,8 @@ module Hoe::Publish
 
     desc 'Publish RDoc to RubyForge.'
     task :publish_docs => [:clean, :docs] do
-      config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+      path = File.expand_path("~/.rubyforge/user-config.yml")
+      config = YAML.load(File.read(path))
       host = "#{config["username"]}@rubyforge.org"
 
       remote_dir = "/var/www/gforge-projects/#{rubyforge_name}/#{remote_rdoc_dir}"
@@ -178,7 +179,7 @@ module Hoe::Publish
     end
 
     desc 'Announce your release.'
-    task :announce => [:post_news, :post_blog, :publish_on_announce ]
+    task :announce => [:post_blog, :publish_on_announce ]
   end
 
   def generate_email full = nil

data/lib/hoe/rcov.rb

@@ -18,6 +18,7 @@ module Hoe::RCov
 
         t.test_files = FileList[pattern]
         t.verbose = true
+        t.rcov_opts << Hoe::RUBY_FLAGS
         t.rcov_opts << "--no-color"
         t.rcov_opts << "--save coverage.info"
         t.rcov_opts << "-x ^/"

data/lib/hoe/rubyforge.rb

@@ -11,8 +11,11 @@ require 'rubyforge'
 # release_to_rubyforge:: Release to rubyforge when release task is run.
 
 module Hoe::RubyForge
-  def define_rubyforge_tasks # :nodoc:
+  def initialize_rubyforge
+    dependency_target << ['rubyforge', ">= #{::RubyForge::VERSION}"]
+  end
 
+  def define_rubyforge_tasks # :nodoc:
     # no doco, invisible hook
     task :release_to => :release_to_rubyforge
 

data/test/test_hoe.rb

@@ -51,15 +51,25 @@ class TestHoe < MiniTest::Unit::TestCase
     assert_match(/^Hoe.*Rakefiles$/, spec.summary)
     assert_equal files.grep(/^test/), spec.test_files
 
-    deps = spec.dependencies
+    deps = spec.dependencies.sort_by { |dep| dep.name }
 
-    assert_equal 1, deps.size
+    assert_equal %w(gemcutter hoe rubyforge), deps.map { |dep| dep.name }
 
-    dep = deps.first
+    dep = deps.shift
+    assert_equal 'gemcutter', dep.name
+    assert_equal :development, dep.type
+    version = Gem.loaded_specs['gemcutter'].version
+    assert_equal ">= #{version}", dep.version_requirements.to_s
 
+    dep = deps.shift
     assert_equal 'hoe', dep.name
     assert_equal :development, dep.type
     assert_equal ">= #{Hoe::VERSION}", dep.version_requirements.to_s
+
+    dep = deps.shift
+    assert_equal 'rubyforge', dep.name
+    assert_equal :development, dep.type
+    assert_equal ">= #{::RubyForge::VERSION}", dep.version_requirements.to_s
   end
 
   def test_plugins
@@ -69,7 +79,6 @@ class TestHoe < MiniTest::Unit::TestCase
     Hoe.plugin :first, :second
     assert_equal before + [:first, :second], Hoe.plugins
   ensure
-    # FIX: maybe add Hoe.reset
     Hoe.plugins.replace before
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hoe
 version: !ruby/object:Gem::Version 
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors: 
 - Ryan Davis
@@ -30,9 +30,29 @@ cert_chain:
   FBHgymkyj/AOSqKRIpXPhjC6
   -----END CERTIFICATE-----
 
-date: 2009-12-08 00:00:00 -08:00
+date: 2010-01-06 00:00:00 -08:00
 default_executable: 
 dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rubyforge
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: gemcutter
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.2.1
+    version: 
 - !ruby/object:Gem::Dependency 
   name: rake
   type: :runtime
@@ -44,25 +64,26 @@ dependencies:
         version: 0.8.7
     version: 
 - !ruby/object:Gem::Dependency 
-  name: rubyforge
-  type: :runtime
+  name: minitest
+  type: :development
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.0.3
+        version: 1.4.2
     version: 
 description: |-
-  Hoe is a rake/rubygems helper for project Rakefiles. It helps generate
-  rubygems and includes a dynamic plug-in system allowing for easy
-  extensibility. Hoe ships with plug-ins for all your usual project
-  tasks including rdoc generation, testing, packaging, and deployment.
+  Hoe is a rake/rubygems helper for project Rakefiles. It helps you
+  manage and maintain, and release your project and includes a dynamic
+  plug-in system allowing for easy extensibility. Hoe ships with
+  plug-ins for all your usual project tasks including rdoc generation,
+  testing, packaging, and deployment.
   
   See class rdoc for help. Hint: `ri Hoe` or any of the plugins listed
   below.
   
-  See Also: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
+  For extra goodness, see: http://seattlerb.rubyforge.org/hoe/Hoe.pdf
 email: 
 - ryand-ruby@zenspider.com
 executables: