rototiller 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: c0293a5f48a1408895a06db0d68fc2c72f6b01f9
-  data.tar.gz: 618d7deee258cfabf05e3ce58444e1b8b5464978
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTczNzRmOTAwNjkwMmFkNGNkYzE2NjFhY2I2YjIwZDcxNDQ3OTgwMQ==
+  data.tar.gz: !binary |-
+    ZDc0MDhjM2E3NWU2NjMwZjYwODAxMjAxNzkyYzRlZjQ1YzU1NjE4MQ==
 SHA512:
-  metadata.gz: 55d4f136476b7486c36c2793fff8b92762dc04fe96a14654ac116e8cc2f3e96c9872f73ab102f473337d67f2a0609cb9caf88e0eb9f5a2d615b8a7b71973be37
-  data.tar.gz: 8780f143c25e5799bb1aa8a1cf36497d26b1c3778efb9deb7039e203646909cc2e0438b28319e70e0fe7cafcdba3a1c3202d3db1dedf7510d66df501fda24762
+  metadata.gz: !binary |-
+    ZTZiZDIzOTgxMmIwM2JiMDVhZTc0ODM4ZjU4YmZjMTU4ZjRjZmZhNTY3NTUw
+    N2I5ZTg3MDg1NzU4MzM4YmUyNTEwZTUyZmZhZDM2ZDJkYmU2ZDgyYjM0NWZj
+    OWQyNTNiN2JmMDMyZTY1MTg0NDU1NGQ4MjUxZmI0NGU0Y2U2MGQ=
+  data.tar.gz: !binary |-
+    NDdjMGM3ZGY0NWZiNTgxODMyZDc0ZWM0YjIyZTlhMWFjNDAxMDllMzVhYWQx
+    ZmQzMWViZDM0MTM4MDcyYjI3MmYxNGM4MTE0ZDMyNTA2MDM1YWI4OWFjNTAx
+    MGQ1ZTdmMzdhMjJmZTcwYTRhMWEyMjUxMDBjYTYyNDIxMDI0NDU=

data/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# How To Contribute To Rototiller
+
+## Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Fork the [Rototiller repository on GitHub](https://github.com/puppetlabs/rototiller)
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is the `master` branch in the case of rototiller
+  * To quickly create a topic branch based on master use `git checkout -b my_contribution master`. Do not work directly on the `master` branch.
+* Make commits of logical _working_ and _functional_ units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+        (BKR-1234) Make the example in CONTRIBUTING imperative and concrete
+
+        Without this patch applied the example commit message in the CONTRIBUTING
+        document is not a concrete example.  This is a problem because the
+        contributor is left to imagine what the commit message should look like
+        based on a description rather than an example.  This patch fixes the
+        problem by making the example concrete and imperative.
+
+        The first line is a real life imperative statement with a ticket number
+        from our issue tracker.  The body describes the behavior without the patch,
+        why this is a problem, and how the patch fixes the problem when applied.
+
+* Make sure you have added [RSpec](http://rspec.info/) tests that exercise your new code.  These test should be located in the appropriate `rototiller/spec/` subdirectory.  The addition of new methods/classes or the addition of code paths to existing methods/classes requires additional RSpec coverage.
+  * One should **NOT USE** the deprecated `should`/`stub` methods - **USE** `expect`/`allow`. Use of deprecated RSpec methods will result in your patch being rejected.  See a nice blog post from 2013 on [RSpec's new message expectation syntax](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/).
+* Run the spec unit tests to assure nothing else was accidentally broken, using `rake test`
+  * **Bonus**: if possible ensure that `[bundle exec] rake test` runs without failures for additional Ruby versions (1.9, 2.0, etc). Rototiller supports Ruby 1.9+, and breakage of support for other rubies will cause a patch to be rejected.
+* Make sure that if you have added new functionality of sufficiently high risk, and it can not be covered adequately via unit tests (mocking, requires disk, other classes, etc), you also include acceptance tests in your PR.
+* Make sure that you have added documentation using [Yard](http://yardoc.org/), new methods/classes without appropriate documentation will be rejected.
+  * Run the yardoc tool to ensure that your yard documentation is properly formatted and complete
+  * `[bundle exec] rake docs:gen`
+* Yard docs are great for other developers, but often are difficult to read for users. If your change impacts user-facing functionality, please include changes to the human-readable markdown docs starting at README.md
+* During the time that you are working on your patch the master Rototiller branch may have changed - you'll want to [rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) before you submit your PR with `git rebase master`.  A successful rebase ensures that your patch will cleanly merge into Rototiller.
+* Submitted patches will be smoke tested through a series of acceptance level tests that ensures basic Rototiller functionality - the results of these tests will be evaluated by a Rototiller team member.  Failures associated with the submitted patch will result in the patch being rejected.
+* Rototiller's Architecture:
+![Rototiller's Architecture](doc/rototiller_class_graph.png)
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](http://links.puppet.com/cla).
+* Push your changes to a topic branch in _your_ fork of the repository.
+* Submit a pull request to [Rototiller](https://github.com/puppetlabs/rototiller)
+* PRs are reviewed as time permits.
+
+# Additional Resources
+
+* [More information on contributing](http://links.puppet.com/contribute-to-puppet)
+* [Contributor License Agreement](http://links.puppet.com/cla)
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+* Questions?  Comments?  Contact the Rototiller team at qa-team@puppet.com
+  * The keyword `rototiller` is monitored and we'll get back to you as quick as we can.

data/MAINTAINERS

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",
+  "issues": "https://tickets.puppetlabs.com/browse/QA",
+  "internal_list": "https://groups.google.com/a/puppet.com/forum/?hl=en#!forum/dept-quality-assurance",
+  "people": [
+    {
+      "github": "er0ck",
+      "email": "erict@puppet.com",
+      "name": "Eric Thompson"
+    },
+    {
+      "github": "zreichert",
+      "email": "zach.reichert@puppet.com",
+      "name": "Zach Reichert"
+    },
+    {
+      "github": "samwoods1",
+      "email": "sam.woods@puppet.com",
+      "name": "Sam Woods"
+    }
+  ]
+}

data/README.md

@@ -1,19 +1,14 @@
 # Rototiller
 
-A [Rake](https://github.com/ruby/rake) helper for command-oriented tasks.
+A [Rake](https://github.com/ruby/rake) helper library for command-oriented tasks.
 
-:warning: This version of Rototiller should be considered of _beta_ quality.
-It is already known that the API will change quite a bit for the next release.
-Please see the notes at the top of the [Write](#write) section.
-
-* simplifies the building of command strings in :rototiller_task for task authors
-* abstracts the overriding of command string components: commands, flags, arguments for task users
-* unifies and standardizes messaging surrounding the use of environment variables for task operations
-* Provides a tool that can house shared rake task code for Puppet.
-* Reduce duplication in Rakefiles across projects at Puppet.
-* Reduce effort required to write first class rake tasks.
-* Reduce time and effort trying to understand requirement to run rake tasks.
-* Provide a standard interface for executing tests in a given test tier regardless of framework (Not MVP)
+## Rototiller Goals
+* Reduce effort required to write first-class rake tasks
+* Reduce time and effort to understand how to run rake tasks
+* Simplifies the building of command strings in :rototiller_task for task authors
+* Abstracts the overriding of command string components: commands, switches, options, arguments for task users
+* Unifies and standardizes messaging surrounding the use of environment variables for task operations
+* Reduce duplication in Rakefiles across projects
 
 <a name="install"></a>
 ## Install
@@ -21,143 +16,69 @@ Please see the notes at the top of the [Write](#write) section.
 
 <a name="write"></a>
 ## Write
-Rototiller provides a Rake DSL addition called 'rototiller_task' which is a fully featured Rake task with environment variable handling, messaging and command-string-building functionality.
-
-:warning: The API below will change for the next release.
-The known changes include (not comprehensive):
-* moving `#add_flag` to `Command` and renaming it `#add_option`
-* adding `#add_env` to `Command` and `#add_option`, so one can add multiple environment variables
-* adding `#add_switch` to Command so one does not have to use the `:is_boolean` parameter for `#add_flag`
-* adding some sort of env_var type so one does not have to use the `:required` parameter for `#add_flag`
-* the above will allow for multiple commands in a task with independent option, switch, and environment variable tracking
-
-Examples (see the [Use](#use) section for outputs):
-    require 'rototiller'
-
-    desc "task dependencies work. this one also uses an environment variable"
-    rototiller_task :parent_task do |task|
-      # most method initializers take either a hash, or block syntax (see next task)
-      task.add_env({:name     => 'RANDOM_VAR', :default => 'default value'})
-      task.add_command({:name => "echo 'i am testing everything with $RANDOM_VAR = #{ENV['RANDOM_VAR']}'"})
-    end
-
-    desc "override command-name with environment variable"
-    rototiller_task :test => :parent_task do |task|
-      # block syntax here. We give up some lines for more readability
-      task.add_command do |cmd|
-        cmd.name         = 'test'
-        cmd.override_env = 'ECHO_EXECUTABLE'
-      end
-      task.add_flag({:name => '-f', :default => 'Rakefile'})
-    end
-
-    desc "override flag values with environment variables"
-    rototiller_task :test_flag_env do |task|
-      task.add_command do |cmd|
-        cmd.name = 'test'
-      end
-      task.add_flag do |flag|
-        flag.name         = '-f'
-        flag.default      = 'Rakefile'
-        flag.override_env = 'FLAG_VALUE'
-      end
-    end
+Rototiller provides a Rake DSL addition called '[rototiller_task](docs/rototiller_task_reference.md)' which is a fully featured Rake task with environment variable handling, messaging and command-string-building functionality.
 
-    desc "do not include flag if the final value (either the default or override_env) is nil or empty and not required. add and control switches or boolean flags"
-    rototiller_task :test_flag_env do |task|
-      task.add_command do |cmd|
-        cmd.name = 'test'
-      end
-      task.add_flag do |flag|
-        flag.name         = '-f'
-        flag.default      = ''
-        flag.override_env = 'FLAG_VALUE'
-        flag.required     = false
-      end
-      # examples:
-      # add a boolean option (switch)
-      #task.add_flag({:name => '--switch1', :is_boolean => true})
-      # add a switch which defaults to "off"
-      #task.add_flag({:name => '-s',  :default => '', :is_boolean => true})
-      # add a switch with environment override
-      #task.add_flag({:name => '--switch3', :is_boolean => true, :override_env => 'TEST_FLAG_ENV_SWITCH3'})
-    end
-
-
-    desc "override command argument values with environment variables"
-    rototiller_task :test_arg_env do |task|
-      task.add_command do |cmd|
-        cmd.name                  = 'ls'
-        cmd.argument              = 'Rakefile'
-        cmd.argument_override_env = 'FILENAME'
-      end
-    end
+Rototiller has 4 main _types_ of arguments that can be passed to a command in a task. `RototillerTasks` can accept multiple commands.  Each of these argument types has a similar API that looks similar to `#add_command`.
 
 <a name="use"></a>
 ## Use
-(with the above sample Rakefile)
+It's just like normal Rake. We just added a bunch of environment variable handling and messaging!
+(with the below example Rakefile):
 
     $) rake -T
-    rake parent_task  # some parent task
-    rake test         # test all the things
+    rake child        # override command-name with environment variable
+    rake parent_task  # parent task for dependent tasks
 
     $) rake -D
-    rake parent_task
-        task dependencies work. this one also uses an environment variable
-    rake test
+    rake child
         override command-name with environment variable
 
-    # added environment variable defaults are set, implicitly, if not found
-    #   this way, their value can be used in the task
-    $) rake test
-    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'default value':
-    i am testing everything with $RANDOM_VAR = default value
-    The CLI flag -f will be used with value Rakefile.
-
-    $) rake parent_task RANDOM_VAR=redrum
-    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'redrum':
-    i am testing everything with $RANDOM_VAR = redrum
-
-    $) rake test ECHO_EXECUTABLE='ls' --verbose
-    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'default value':
-    echo 'i am testing everything with $RANDOM_VAR = default value'
-    i am testing everything with $RANDOM_VAR = default value
-    The CLI flag -f will be used with value Rakefile.
-
-    ls -f Rakefile
-    Rakefile
-
-    $) rake test_flag_env
-    The CLI flag -f will be used with value Rakefile.
-    $) echo $?
-    0
-
-    $) rake test_flag_env --verbose
-    The CLI flag -f will be used with value Rakefile.
-
-    test -f Rakefile
+    rake parent_task
+        parent task for dependent tasks. this one also uses two environment variables and two commands
 
-    $) rake test_flag_env --verbose FLAG_VALUE='README.md'
-    The CLI flag -f will be used with value README.md.
+### The old way
 
-    test -f README.md
+    desc 'the old, bad way. This is for the README.md file.'
+      task :demo_old do |t|
+        echo_args = ENV['COMMAND_NAME'] || "my_sweet_command #{ENV['HOME']}"
+        overriding_options = ENV['OPTIONS'].to_s
+        args = [echo_args, *overriding_options.split(' '), '--switch'].compact
+        sh("echo", *args)
+      end
 
-    $) rake test_flag_env --verbose FLAG_VALUE='nonesuch'
-    The CLI flag -f will be used with value README.md.
+this does, _mostly_ the same as below.  but what do the various environment variables do?  they aren't documented anywhere, especially in Rake's output. why do we have to split on a space for the overriding options?  why do we compact?  We shouldn't have to do this in all our Rakefiles, and then forget to do it, _correctly_ in most.  Rototiller does all this for us, but uniformly handling environment variables for any command piece, optionally. But anytime we do, we automatically get messaging in Rake's output, and this can be controlled with Rake's --verbose flag.  Now we don't have to dig into the Rakefile to see what the author intended for an interface.  Now we can provide a uniform interface for our various tasks based upon this library and have messaging come along for the ride.  Now we can remove the majority of repeated code from our Rakefiles.
 
-    test -f README.md
-    test -f nonesuch failed
+### The rototiller way
 
-    $) rake test_arg_env
-    Rakefile
+    require 'rototiller'
+    desc 'the new, rototiller way. This is for the README.md file.'
+      rototiller_task :demo_new do |t|
+        t.add_env({:name => 'FOO', :message => 'I am describing FOO, my task needs me, but has a default. this default will be set in the environment unless it exists', :default => 'FOO default'})
+        t.add_env do |e|
+          e.name    = 'HOME'
+          e.message = 'I am describing HOME, my task needs me. all rototiller methods can take a hash or a block'
+        end
+
+        t.add_command do |c|
+          c.name = 'echo my_sweet_command ${HOME}'
+          c.add_env({:name => 'COMMAND_NAME', :message => 'use me to override this command name (`echo my_sweet_command`)'})
+          # anti-pattern: this is really an option.  FIXME once add_option is implemented
+          c.add_switch({:name => '--switch ${FOO}', :message => 'echo uses --switch to switch things'})
+          # FYI, add_switch can also take a block and add_env
+          # command blocks also have add_option, and add_arg, each of which can add environment variables which override themselves.
+          # add_option actually has its own add_arg and each of those have add_env.  so meta
+        end
+      end
 
-    $) rake test_arg_env FILENAME=README.md
-    README.md
+### Reference
+* [rototiller\_task reference](docs/rototiller_task_reference.md)
+  * contains usage information on all rototiller_task API methods
 
 ## Issues
 
-* none. it's perfect
+* none. it's perfect, but just in case (sorry, this is Puppet-internal for now)
 * [Jira: Rototiller](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20QA)
+* [Puppet QA-team](mailto:qa-team@puppet.com)
 
 ## More Documentation
 
@@ -174,7 +95,129 @@ Next start the yard server
 
 Finally navigate to http://0.0.0.0:8808/ to view the documentation
 
-## Maintainers
-* [Zach Reichert](zach.reichert@puppetlabs.com), github:[zreichert](https://github.com/zreichert), jira:zach.reichert
-* [Eric Thompson](erict@puppetlabs.com), github:[er0ck](https://github.com/er0ck), jira:erict
-* [QA](qa-team@puppetlabs.com)
+## Contributing
+* [Contributing](CONTRIBUTING.md)
+
+## abandon hope, all ye who enter here
+### All permutations of v2 API (remove and refactor into useful doc sections below upon testing, merge-up to stable)
+
+* all things that can take multiples should use add\_ as precursor to method name
+* all things that only take one should use set\_ as precursor to method name?
+    require 'rototiller'
+
+    ## all task methods
+    rototiller_task :name do |t|
+      t.add_command # t.add_cmd? me no likey
+      t.add_env
+    end
+    rototiller_task do |t|
+      t.set_name = 'string_name' # should this be validated??  e.g.: spaces, etc
+      t.add_command
+      t.add_env
+    end
+
+
+    ## all task's add_env invocations with just name
+    t.add_env('env_name') #required, default messaging
+    t.add_env :env_name
+    t.add_env 'env_name' # implicitly allowed by ruby
+    t.add_env do |e|
+      e.name
+    end
+
+    ## all task's add_env invocations with name, message
+    #t.add_env('env_name')  # impossible
+    t.add_env :env_name do |e|
+    t.add_env 'env_name' do |e|  # should we do this too?
+      e.set_message
+    end
+    t.add_env do |e|
+      e.name
+      e.message
+    end
+
+    ## all task's add_env invocations with name, value
+    #t.add_env('env_name')  # impossible
+    t.add_env :env_name do |e|
+    t.add_env 'env_name' do |e|  # should we do this too?
+      e.default/value  # does value imply the env will be set by rototiller?  does default NOT?
+    end
+    t.add_env do |e|
+      e.name
+      e.default/value
+    end
+
+    ## all task's add_env invocations with name, value, message
+    #t.add_env('env_name')  # impossible
+    t.add_env :env_name do |e|
+      e.default/value  # does value imply the env will be set by rototiller?  does default NOT?
+      e.message
+    end
+    t.add_env do |e|
+      e.name
+      e.default/value
+      e.message
+    end
+
+
+    ## all task's add_command invocations with only name
+    # default messaging, no env override?
+    t.add_command('echo --blah my name is ray')
+    t.add_command :echo
+    t.add_command 'echo'
+    t.add_command do |c|
+      c.name = 'echo'
+    end
+
+    ## all task's add_command invocations with name (string), message
+    #t.add_command('echo --blah my name is ray', 'message') # ArgumentError
+    t.add_command :echo
+    t.add_command 'echo' do |c|
+      c.name = 'echo' # # nomethod error?
+      c.message = 'why we echo'
+    end
+    t.add_command do |c|
+      c.name = 'echo'
+      c.message = 'blah'
+    end
+
+    ## all task's add_command invocations with name (block) (could be same for message?)
+    #t.add_command('echo --blah my name is ray', 'message') # ArgumentError
+    #t.add_command :echo
+    #t.add_command 'echo' do |c|
+    #  c.message = 'blah'
+    #end
+    t.add_command do |c|
+      c.name 'echo' do |n|
+        n.add_env
+      end
+      c.add_arg 'some_arg' do |a|
+        a.add_env
+        a.message
+      end
+      c.add_option '--option_name' do |o|
+        o.add_arg 'switch_arg' do |a|
+          a.add_env 'opion-arg_env' do |e|
+            e.set_name
+            e.set_message
+            e.set_value
+          end
+        end
+        o.add_env 'option-name_env' do |e|
+          e.set_name
+          e.set_message
+          e.set_value
+        end
+        o.message
+      end
+      c.add_switch '--some_switch' do |s|
+        s.add_env 'env_name' do |e|
+          e.set_name
+          e.set_message
+          e.set_value
+        end
+        s.message
+      end
+    end
+
+    #should we be able to add an env for any given message?  i don't see a use case, we should probably just save users from themselves here.