volley 0.1.9 → 0.1.10

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v0.1.9:
+* remove dependency on awesome_print and debug statements. fail me.
+* more docopt fixes
+* handle docopt exit for --version
+* update to use newest docopt version
+* working on getting 'auto' source working
+
 ## v0.1.8:
 * more docopt fixes
 

data/README.md

@@ -1,24 +1,137 @@
 # Volley
 
-TODO: Write a gem description
+`Volley` is a Publish/Subscribe deployment mechanism, with some additional functionality allowing
+for scripting of builds. It depends on MCollective as the Publish/Subscribe mechanism.
 
 ## Installation
 
+Volley requires Fog, which requires Nokogiri. Nokogiri requires ruby 1.9.3 and libxml2
+(and possibly libxslt1). To get libxml2 set up, use the following command:
+
+### MacOSX
+
+    brew install libxml2
+
+### Ubuntu
+
+    sudo apt-get install libxml2-dev libxslt1-dev
+
+now back to your regularly scheduled gem install.
+
+### Gem installation
+
 Add this line to your application's Gemfile:
 
     gem 'volley'
 
 And then execute:
 
-    $ bundle
+    bundle
 
 Or install it yourself as:
 
-    $ gem install volley
+    gem install volley
+
+By default, volley stores it's data in /opt/volley, you'll need to create this directory and make sure it's world writable.
+
+    sudo mkdir -p /opt/volley
+    sudo chmod 777 /opt/volley
+
+## Configuration
+
+Generally, you will provide configuration in either a `/etc/Volleyfile` or `~/.Volleyfile`. It should be either/or, because
+certain configurations (publisher) can only be specified once.
+
+### Publisher
+
+For testing, you can use a `Local` publisher:
+
+    publisher :local,
+      :directory => "/tmp/volley/remote"
+
+This will allow you to use all of `Volley`'s functionality without requiring a cloud account.
+
+Eventually, you will need to configure a cloud-based publisher, for S3, it would look like this:
+
+    publisher :amazons3,
+      :aws_access_key_id => "ACCESS_KEY",
+      :aws_secret_access_key => "SECRET_KEY",
+      :bucket => "my-bucket-name"
 
 ## Usage
 
-TODO: Write usage instructions here
+Usage of `Volley` comes in primarily two parts: Publish and Deploy. Publishing generally involves creating an artifact
+and pushing it to a remote location like S3. Deploying involves pulling the artifact from the remote location and running
+code contained inside of it.
+
+### Volleyfile
+
+All of the intelligence required to build, publish and deploy a project should be contained in the project's `Volleyfile`
+If you've used `Capistrano` or other similar gem's, this is similar.
+
+A project's `Volleyfile` contains at least a single project with publish and deploy plans.
+
+    project :myproject do
+      plan :publish do
+        action :build do
+          # run a build command
+        end
+        push do
+          # push is a special action.
+          # the push action will automatically create a single artifact for you
+          # the last statement of the push action should be a list of files that
+          # you want included in the artifact.
+        end
+      end
+
+      plan :deploy do
+        pull do |dir|
+          # pull is a special action
+          # this action will be called once the artifact is downloaded and unpacked
+          # on the remote server.
+          # 'dir' is set to the directory containing the unpacked contents of the
+          # artifact.
+        end
+      end
+    end
+
+The `Volleyfile` is organized such that:
+
+* `Volleyfile`s contain projects
+* Projects contain plans
+* Plans contain actions (which are run in the order that they are specified)
+
+### Project
+
+A project is simply a container for a given projects related work. The `project` method requires a name argument,
+either a symbol or string. Projects support a few configurations:
+
+* `scm` - specify the source code management being used. currently supports `:git` and `:subversion`
+
+### Plan
+
+As in the above `Volleyfile`, plans are simply a block of code. The `plan` method of the project requires a name argument,
+as a symbol or a string.
+
+### Action
+
+Actions contain simple blocks of work necessary to build your artifact. The simplest form of an action looks like:
+
+    action :name do
+        # work goes here
+    end
+
+As with projects and plans, names can be specified as strings or symbols.
+
+There are a few specialized actions which have shortcut methods:
+
+* `default` - generally used for simple plans, that contain only one action
+* `push` - The push action is specialized in that it's return value is the list of
+  files which will be packaged into the remote artifact. This action is the only
+  way to push files to publisher.
+* `pull` - The pull action is the only how `Volley` pulls artifacts from the publisher.
+  The code block for the pull action should contain the work required to deploy the artifact on the remote server.
+* `volley` - the volley action allows for dependencies between projects, one project can call another.
 
 ## Contributing
 

data/bin/volley

@@ -11,25 +11,6 @@ Usage:
   volley [options] PLAN DESCRIPTOR
   volley [options] PLAN DESCRIPTOR [ARGUMENT ...]
 
-<plan>
-  The plan to run. This can be just the plan name or the project:plan.
-  (will check in the reserved volley project for plan first)
-
-<descriptor>
-  A descriptor should conform to the following format:
-    <project>[@<branch>[:<version>]]
-
-  project:  the project name.
-  branch:   the branch name.
-            Defaults to the branch currently in use,
-            must be specified for remote mode.
-  version:  the version (revision)
-            Defaults to the current revision
-            In remote mode, defaults to "latest"
-
-<argument>
-  A list of key=value pairs
-
 Options:
   -h --help           show this help message and exit
      --version        show version and exit
@@ -60,7 +41,9 @@ module Volley
       log         = options["--log"]
       level       = options["--level"]
       force       = options["--force"]
-      args        = { }
+      plan        = options["PLAN"]
+      desc        = options["DESCRIPTOR"]
+      kvs         = options["ARGUMENT"]
 
       Volley::Dsl::VolleyFile.init
       Volley::Dsl::VolleyFile.load(config, :optional => true)
@@ -76,11 +59,10 @@ module Volley
         Volley::Log.console_quiet
       end
 
-      kvs = argv.select { |e| e.match(/(\w+)\=(\w+)/) }
-      pos = argv.reject { |e| e.match(/(\w+)\=(\w+)/) }
-
-      plan = pos.shift
-      desc = pos.shift
+      if desc && !Volley::Descriptor.valid?(desc)
+        kvs.unshift(desc)
+        desc = nil
+      end
 
       raise "must specify plan" unless plan
       if plan =~ /\:/
@@ -102,7 +84,6 @@ module Volley
         Volley::Log.debug "## OPTIONS ##"
         Volley::Log.debug "plan:       #{plan}"
         Volley::Log.debug "descriptor: #{desc}"
-        Volley::Log.debug "positional: #{pos.join(",")}"
         Volley::Log.debug "key:value:  #{kvs.join(",")}"
       end
 

data/init/Volleyfile

@@ -1 +1,24 @@
-# TODO: write this
+
+project :myproject do
+  plan :publish do
+    action :build do
+      # run a build command
+    end
+    push do
+      # push is a special action.
+      # the push action will automatically create a single artifact for you
+      # the last statement of the push action should be a list of files that
+      # you want included in the artifact.
+    end
+  end
+
+  plan :deploy do
+    pull do |dir|
+      # pull is a special action
+      # this action will be called once the artifact is downloaded and unpacked
+      # on the remote server.
+      # 'dir' is set to the directory containing the unpacked contents of the
+      # artifact.
+    end
+  end
+end

data/lib/volley/descriptor.rb

@@ -29,5 +29,14 @@ module Volley
     def to_s
       "#@project@#@branch:#@version"
     end
+
+    class << self
+      def valid?(desc)
+        return false if desc.nil? || desc.blank?
+        list = desc.split(/[\@\:\.\/\\\-]/)
+        return false if (list.count < 2 || list.count > 3)
+        true
+      end
+    end
   end
 end

data/lib/volley/version.rb

@@ -3,7 +3,7 @@ unless defined?(Volley::Version)
     module Version
       MAJOR  = 0
       MINOR  = 1
-      TINY   = 9
+      TINY   = 10
       TAG    = nil
       STRING = [MAJOR, MINOR, TINY, TAG].compact.join('.')
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volley
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-06 00:00:00.000000000 Z
+date: 2012-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp