From 5003d5a43165868976352d8b217b6e75b90c221b Mon Sep 17 00:00:00 2001 From: Ryan Davis Date: Thu, 3 Apr 2014 16:27:09 -0800 Subject: + Added :rdoc plugin. + Renamed History.txt to History.rdoc. + Renamed README.txt to README.rdoc. Deleted stale redocs task. Massive cleanup in test_hoe.rb by making hoe helper take *skips & &block [git-p4: depot-paths = "//src/hoe/dev/": change = 9335] --- README.rdoc | 311 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100644 README.rdoc (limited to 'README.rdoc') diff --git a/README.rdoc b/README.rdoc new file mode 100644 index 0000000..6ae068a --- /dev/null +++ b/README.rdoc @@ -0,0 +1,311 @@ += Hoe + +home :: http://www.zenspider.com/projects/hoe.html +code :: https://github.com/seattlerb/hoe +bugs :: https://github.com/seattlerb/hoe/issues +rdoc :: http://docs.seattlerb.org/hoe/ +doco :: http://docs.seattlerb.org/hoe/Hoe.pdf +other :: http://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: http://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 + +manifest [noun] a document giving comprehensive +details of a ship and its cargo and other contents, passengers, and +crew for the use of customs officers. + +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. + + "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::Inline +* Hoe::Newb +* Hoe::Package +* Hoe::Publish +* Hoe::Racc +* Hoe::RCov +* Hoe::Signing +* Hoe::Test + +=== Known 3rd-Party Plugins: + +* hoe-bundler - Generates a Gemfile based on a Hoe's declared dependencies. +* hoe-debugging - A Hoe plugin to help you debug your codes. +* hoe-deveiate - A collection of Rake tasks and utility functions. +* hoe-doofus - A Hoe plugin that helps me keep from messing up gem releases. +* hoe-gemcutter - Adds gemcutter release automation to Hoe. +* hoe-geminabox - Allows you to push your gems to geminabox +* hoe-gemspec - Generate a prerelease gemspec based on a Hoe spec. +* hoe-gemspec2 - ??? submit a PR to add description +* hoe-git - A set of Hoe plugins for tighter Git integration. +* hoe-heroku - Helps you get your stuff on Heroku. +* hoe-hg - A Hoe plugin for Mercurial integration. +* hoe-highline - A Hoe plugin for building interactive Rake tasks +* hoe-ignore - ??? submit a PR to add description +* hoe-manifest - ??? submit a PR to add description +* hoe-manualgen - A manual-generation plugin for Hoe +* hoe-mercurial - A Hoe plugin for Mercurial integration. +* hoe-reek - Integrates the reek code smell engine into your hoe projects. +* hoe-roodi - Integrates the roodi code smell tool into your hoe projects. +* hoe-rubygems - Additional RubyGems tasks. +* hoe-seattlerb - Minitest, email announcements, release branching. +* hoe-telicopter - Provides tasks used by hotelicopter. +* hoe-travis - Allows your gem to gain maximum benefit from . +* hoe-version - ??? submit a PR to add description +* hoe-yard - A Hoe plugin for generating YARD documentation. + +=== 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 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** `initialize_#{plugin}` +methods called followed by their **optional** +`activate_#{plugin}_deps` methods called. This lets them set needed +instance variables to default values and declare any gem dependencies +needed.. Finally, the hoe-spec block is evaluated so that project +specific values can override the defaults. + +See "Hoe Plugin Loading Sequence" in hoe.rb for full details. + +==== 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. + +== REQUIREMENTS: + +* rake +* rubygems + +== INSTALL: + +* sudo gem install hoe + +== LICENSE: + +(The MIT License) + +Copyright (c) Ryan Davis, seattle.rb + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -- cgit v1.2.1