= Hoe

home :: https://zenspider.com/projects/hoe.html code :: https://github.com/seattlerb/hoe bugs :: https://github.com/seattlerb/hoe/issues doco :: https://docs.seattlerb.org/hoe/ doco2 :: https://docs.seattlerb.org/hoe/Hoe.pdf clog :: https://github.com/seattlerb/hoe/blob/master/History.rdoc other :: https://github.com/jbarnette/hoe-plugin-examples

== DESCRIPTION:

Hoe is a rake/rubygems helper for project Rakefiles. It helps you manage, 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, deployment, and announcement.

See class rdoc for help. Hint: ri Hoe or any of the plugins listed below.

For extra goodness, see: https://docs.seattlerb.org/hoe/Hoe.pdf

== FEATURES/PROBLEMS:

• Includes a dynamic plug-in system allowing for easy extensibility.
• Auto-intuits changes, description, summary, and version.
• Uses a manifest for safe and secure deployment.
• Provides 'sow' for quick project directory creation.
• 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><b>manifest [noun]</b> 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 <em>do not</em>. "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.

"Ultimately, the manifest represents professionalism of the
 deployment process – making sure you know what you think you are
 releasing. Auto-generating the manifest should be avoided – and
 this comes from a man who loves to generate things."

-- dr nic

=== 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 rubygems.org.
• Posts news of the release my blog.
• Sends an announcement email. (via the hoe-seattlerb plugin gem)

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
• Hoe::Compiler
• Hoe::Debug
• Hoe::Deps
• Hoe::Flay
• Hoe::Flog
• Hoe::GemPreludeSucks
• Hoe::Gemcutter
• Hoe::Git
• Hoe::Inline
• Hoe::Newb
• Hoe::Package
• Hoe::Publish
• Hoe::Racc
• Hoe::RCov
• Hoe::Signing
• Hoe::Test

=== Known 3rd-Party Plugins:

• hoe-bundler - Generate a Gemfile based on a Hoe spec's declared dependencies. (Mike Dalessio)
• hoe-debugging - A Hoe plugin to help you debug your C extensions (John Barnette)
• hoe-deveiate - A collection of Rake tasks and utility functions I use to maintain my Open Source projects (Michael Granger)
• hoe-doofus - A Hoe plugin that helps me (and you, maybe?) keep from messing up gem releases (John Barnette)
• hoe-gemcutter - Adds gemcutter release automation to Hoe. (James Tucker)
• hoe-geminabox - A small hoe plugin that allows you to push your gems to geminabox (Ben Bleything)
• hoe-gemspec - Generate a prerelease gemspec based on a Hoe spec. (Mike Dalessio)
• hoe-gemspec2 - Adds support for generation of gemspec files to Hoe (raggi)
• hoe-git - A set of Hoe plugins for tighter Git integration (John Barnette)
• hoe-git2 - A set of Hoe plugins for tighter Git integration (John Barnette)
• hoe-halostatue - Hoe::Halostatue is a Hoe meta-plugin that provides improved support for Markdown README files, provides features from other plugins, and enables improved support for trusted publishing. (Austin Ziegler)
• hoe-heroku - A Hoe plugin that helps you get your stuff on Heroku (Ben Bleything)
• hoe-hg - A Hoe plugin for Mercurial integration (McClain Looney)
• hoe-highline - A Hoe plugin for building interactive Rake tasks (Michael Granger)
• hoe-ignore - FIX (describe your package) (Evan Phoenix)
• hoe-manns - Collection of some personal used tasks (Sascha Manns)
• hoe-manualgen - A manual-generation plugin for Hoe (Michael Granger)
• hoe-markdown - Hoe plugin with helpers for markdown documentation files. (Mike Dalessio)
• hoe-mercurial - This is a fork of the hoe-hg plugin (Michael Granger)
• hoe-packaging - Collection of some personal used tasks for creating and deploying RPM and DEB packages. (Sascha Manns)
• hoe-reek - Tasks to integrate the reek code smell engine into your hoe projects (Sascha Manns)
• hoe-roodi - hoe-roodi is a Hoe plugin to integrate the roodi code smell tool into your hoe projects. (Erik Hollensbe)
• hoe-rubocop - This hoe plugin extends hoe for using some rake tasks to control rubocop. (Sascha Manns)
• hoe-rubygems - A Hoe plugin with additional RubyGems tasks (John Barnette)
• hoe-seattlerb - Hoe plugins providing tasks used by seattle.rb including minitest, perforce, and email providing full front-to-back release/announce automation. (Ryan Davis)
• hoe-telicopter - Hoe plugin providing tasks used by hotelicopter, currently just the email plugin from the seattlerb plugin by Ryan Davis (jim nist)
• hoe-travis - hoe-travis is a Hoe plugin that allows your gem to gain maximum benefit from https://travis-ci.org (Eric Hodel)
• hoe-version - Hoe plugin to provide rake tasks to bump version (bhenderson)
• hoe-yard - A Hoe plugin for generating YARD documentation (Postmodern)

=== Writing Plugins:

A plugin can be as simple as:

module Hoe::Thingy
  attr_accessor :thingy

  def initialize_thingy # optional
    self.thingy = 42
  end

  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.

=== How Plugins Work

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 p