puppet 2.7.23 → 2.7.24

data/Gemfile

@@ -1,17 +1,33 @@
-source :rubygems
+source "https://rubygems.org"
 
-gemspec
+def location_for(place)
+  if place =~ /^(git:[^#]*)#(.*)/
+    [{ :git => $1, :branch => $2, :require => false }]
+  elsif place =~ /^file:\/\/(.*)/
+    ['>= 0', { :path => File.expand_path($1), :require => false }]
+  else
+    [place, { :require => false }]
+  end
+end
 
 group(:development, :test) do
-  gem "facter", "~> 1.6.4", :require => false
-  gem "rack", "~> 1.4.1", :require => false
-  gem "rspec", "~> 2.10.0", :require => false
+  gem "puppet", :path => File.dirname(__FILE__), :require => false
+  gem "facter", *location_for(ENV['FACTER_LOCATION'] || '~> 1.6')
+  gem "hiera", *location_for(ENV['HIERA_LOCATION'] || '~> 1.0')
+  gem "rack", "~> 1.4", :require => false
+  gem "rake", :require => false
+  gem "rspec", "~> 2.11.0", :require => false
   gem "mocha", "~> 0.10.5", :require => false
+  gem "activerecord", *location_for('~> 3.0.7')
+  gem "couchrest", *location_for('~> 1.0')
+  gem "net-ssh", *location_for('~> 2.1')
+  gem "puppetlabs_spec_helper"
+  gem "sqlite3"
+  gem "stomp"
+  gem "tzinfo"
 end
 
 platforms :mswin, :mingw do
-  # See http://jenkins.puppetlabs.com/ for current Gem listings for the Windows
-  # CI Jobs.
   gem "sys-admin", "~> 1.5.6", :require => false
   gem "win32-api", "~> 1.4.8", :require => false
   gem "win32-dir", "~> 0.3.7", :require => false

data/ext/packaging/LICENSE

@@ -0,0 +1,17 @@
+   packaging - Puppet Labs packaging framework
+
+   Copyright (C) 2011-2013 Puppet Labs Inc
+
+   Puppet Labs can be contacted at: info@puppetlabs.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/ext/packaging/README.md

@@ -123,7 +123,8 @@ specified in the build-data file, and appropriate membership in the build
 groups, e.g. to use mock on the builder, membership in the mock group. This is
 a major hurdle, and is resolved with the `jenkins` tasks below.
 
-## `:jenkins:` tasks
+## legacy `:jenkins:` workflow tasks
+(Deprecated - see "dyamic jenkins task workflow" below)
 Jenkins tasks are similar to the `:remote:` tasks, but they do not require ssh
 access to the builders. They do require being on the local network - the
 jenkins instance that performs package builds is an internal server only,
@@ -150,6 +151,10 @@ repository](https://github.com/puppetlabs/build-data)
 later in determining the target for the build artifacts on the distribution
 server
 
+4) $METRICS - a string of data points related to the build which are used for
+data analysis. Contents of this string are items which cannot be obtained from
+within the Jenkins job itself.
+
 5) $DOWNSTREAM\_JOB - The URL of a downstream job that jenkins should post to
 upon success. This is obtained via the DOWNSTREAM\_JOB environment variable.
 
@@ -206,14 +211,25 @@ the task are:
 
 #################
 ```
-The second, more recent, jenkins-based workflow is for initiating the
-"uber_build", or a package build for all of our target platforms. This workflow
-doesn't actually use a static job on the jenkins-server. Instead it _creates_
-the jenkins jobs for you, on-demand. Specifically, it creates two jenkins-jobs,
-and can create an optional third.
+
+To gather metrics related to a Jenkins build, the Groovy Postbuild plugin is used.
+For tasks carried out on the static Jenkins job, the script must be manually added to the job's
+configuration. The script in its entirety can be seen [here.](https://github.com/Whopper92/buildboard#groovyScript)
+
+## dynamic `:jenkins:` task workflow
+
+The recommended and far simpler jenkins-based workflow is for initiating the
+"uber_build", or a package build for all of our target platforms.
+
+The uber_build is invoked as "pl:jenkins:uber_build" or "pe:jenkins:uber_build"
+depending on if this is a FOSS or PE package.
+
+This workflow doesn't actually use a static job on the jenkins-server. Instead
+it _creates_ the jenkins jobs for you, on-demand. Specifically, it creates two
+jenkins-jobs, and can create an optional third.
 
 The first job is a matrix job, the cells of which are individual package tasks
-for all of the build targets. This job takes three parameters:
+for all of the build targets. This job takes four parameters:
 
 1) $PROJECT\_BUNDLE - a tar.gz of a git-bundle from HEAD of the current
 project, which is cloned on the builder to set up a duplicate of this
@@ -226,11 +242,16 @@ about the build
 later in determining the target for the build artifacts on the distribution
 server
 
+4) $METRICS - a string of data points related to the build which are used for data
+analysis. Contents of this string are items which cannot be obtained from within
+the Jenkins job itself. Note that the Groovy postbuild script needed for metrics
+gathering is dynamically passed to each job.
+
 This first job clones the git bundle passed in as a parameter, then clones the
 packaging repo (rake package:bootstrap) and for every cell in its matrix
 performs a package build for a specific target (e.g. rake pl:deb
-COW=base-lucid-i386.cow). If all cells in the matrix complete successfully (if
-all packages build), this job automatically triggers the second of the new jobs
+COW=base-lucid-i386.cow). Once all cells in the matrix complete (either succeed
+or fail), this job automatically triggers the second of the new jobs
 as a downstream job.
 
 To receive an email notification from jenkins about the status of the packaging
@@ -243,15 +264,34 @@ The second job is an automatic repository creation task for this git repo.
 Specifically, the job copies the git bundle from the packaging job and clones
 it, and uses the git information in the git bundle to clone the packaging repo
 and invoke the repository creation jobs `pl:jenkins:rpm_repos` and
-`pl:jenkins:deb_repos`.
+`pl:jenkins:deb_repos`. The job will always be invoked, but will only actually
+create repos if the upstream packaging job actually succeeded.
 
 The third job is only created _if_ the environment variable
 `DOWNSTREAM_JOB=<job_url>` was passed to the initial "pl:jenkins:uber_build"
 invocation. This third job takes the value assigned to `DOWNSTREAM_JOB` and
 creates a proxy jenkins job with a single build step, a curl call to this
 value, presumably a url to a jenkins job to trigger programmatically.
-Once the repos have successfully been created by the second job, the third job
-will automatically trigger as a downstream job.
+
+An important note about `DOWNSTREAM_JOB`: `DOWNSTREAM_JOB` in the dynamic jenkins
+workflow is _always_ invoked if it is passed in as an environment variable.
+However, it is also appended with an additional parameter, `PACKAGE_BUILD_STATUS`,
+which will be the string "success" if package and repo builds succeeded, or
+"failure" if package or repo builds failed. By modifying the actual downstream
+jenkins job to accept a string parameter of `PACKAGE_BUILD_STATUS`, one can
+switch on the success or failure of the packaging job, responding
+  appropriately.
+
+E.g., a job url:
+http://jenkins.example.net/job/downstream/buildWithParameters?FOO=bar
+
+in the success case will be transformed into
+
+http://jenkins.example.net/job/downstream/buildWithParameters?FOO=bar&PACKAGE_BUILD_STATUS=success
+
+and in the failure case transformed into
+
+http://jenkins.example.net/job/downstream/buildWithParameters?FOO=bar&PACKAGE_BUILD_STATUS=failure
 
 All 3 jobs are configured by default for removal by jenkins after 3 days, to
 avoid clutter.
@@ -260,6 +300,7 @@ The goal is to move toward migrating all of the jenkins tasks from the first
 workflow, using a static job that is called many times per package, to this
 second workflow of creating the jobs on demand.
 
+
 ## Task Explanations
 For a listing of all available tasks and their functions, see the [Task
 Dictionary](https://github.com/puppetlabs/packaging/tree/more_documentation#task-dictionary)
@@ -293,17 +334,20 @@ spec file, and an osx preflight and plist.
 
 The top level Rakefile or a separate task file in the project should have the following added:
 
+(this assumes RAKE\_ROOT is defined in the top-level Rakefile using something like the following)
 ```ruby
-Dir['ext/packaging/tasks/**/*.rake'].sort.each { |t| load t }
+RAKE_ROOT = File.expand_path(File.dirname(__FILE__))
+```
 
-build_defs_file = 'ext/build_defaults.yaml'
+```ruby
+build_defs_file = File.join(RAKE_ROOT, 'ext', 'build_defaults.yaml')
 if File.exist?(build_defs_file)
   begin
     require 'yaml'
     @build_defaults ||= YAML.load_file(build_defs_file)
   rescue Exception => e
     STDERR.puts "Unable to load yaml from #{build_defs_file}:"
-    STDERR.puts e
+    raise e
   end
   @packaging_url  = @build_defaults['packaging_url']
   @packaging_repo = @build_defaults['packaging_repo']
@@ -313,20 +357,25 @@ if File.exist?(build_defs_file)
   namespace :package do
     desc "Bootstrap packaging automation, e.g. clone into packaging repo"
     task :bootstrap do
-      if File.exist?("ext/#{@packaging_repo}")
+      if File.exist?(File.join(RAKE_ROOT, "ext", @packaging_repo))
         puts "It looks like you already have ext/#{@packaging_repo}. If you don't like it, blow it away with package:implode."
       else
-        cd 'ext' do
+        cd File.join(RAKE_ROOT, 'ext') do
           %x{git clone #{@packaging_url}}
         end
       end
     end
     desc "Remove all cloned packaging automation"
     task :implode do
-      rm_rf "ext/#{@packaging_repo}"
+      rm_rf File.join(RAKE_ROOT, "ext", @packaging_repo)
     end
   end
 end
+
+begin
+  load File.join(RAKE_ROOT, 'ext', 'packaging', 'packaging.rake')
+rescue LoadError
+end
 ```
 
 Also in ext should be two files, build_defaults.yaml and project_data.yaml.
@@ -388,6 +437,12 @@ summary: 'Light weight hierarchical data store'
 description: 'A pluggable data store for hierarcical data'
 # file containing hard coded version information, if present
 version_file: '/lib/hiera.rb'
+# A string indicating the version strategy for the project (one of 'odd_even' or 'rc_final'), defaults to rc_final
+# odd_even is a final release when the minor version is even, and a development release when it is odd
+# rc_final is a final release when there is no rc at the end of the version string, and a development release when there is
+version_strategy: 'rc_final'
+# Boolean value of whether or not to automatically update the version file before packaging (defaults to false)
+update_version_file: true
 # files and gem\_files are space separated lists
 # files to be packaged into a tarball and released with deb/rpm
 files: '[A-Z]* ext lib bin spec acceptance_tests'
@@ -396,6 +451,12 @@ files: '[A-Z]* ext lib bin spec acceptance_tests'
 # 'tar\_excludes' only needs to include any undesired subdirectories/files of the 'files'
 # list to exclude
 tar_excludes: 'ext/packaging lib/some_excluded_file'
+# Array of templates or globs of templates to evaluate. Note that without this key, the packaging will
+# default to searching for any files in `ext` with the extension '.erb' and evaluate them. When this
+# key is supplied, its values override the defaults, and all desired erb files must be specified with a path or glob.
+templates:
+  - ext/redhat/project.spec.erb
+  - ext/templates/**/*.erb
 # files to be packaged into a gem
 gem_files: '{bin,lib}/**/* CHANGELOG COPYING README.md LICENSE'
 # To exclude specific files from inclusion in a gem:
@@ -417,6 +478,19 @@ gem_runtime_dependencies:
   hiera-json:
 gem_development_dependencies:
   facter: '>= 1.6.11'
+# To add gem dependencies which only apply to a specific platform, add the key "gem_platform_dependencies".
+# The first key under the gem_platform_dependencies has to be a value that
+# corresponds to a value of RUBY_PLATFORM. The subkeys are the same as the
+# top-level gem dependency keys:
+gem_platform_dependencies:
+  x86-mingw32:
+    gem_runtime_dependencies:
+      win32process: '~> 0.6.5'
+    gem_development_dependencies:
+      rake: '~> 0.9.0'
+  x86_64-darwin:
+    gem_runtime_dependencies:
+      CFPropertyList: '~> 2.2.4'
 # rdoc options as an array
 gem_rdoc_options:
   - --line-numbers

data/ext/packaging/spec/tasks/00_utils_spec.rb

@@ -14,16 +14,18 @@ describe "00_utils" do
       :get_rpmversion             => '0.7.0',
       :get_rpmrelease             => '1',
       :is_rc?                     => false,
+      :is_odd?                    => true,
     },
-    '0.7.0rc10'                    => {
-      :git_describe_version       => %w{0.7.0rc10},
-      :get_dash_version           => '0.7.0rc10',
-      :get_ips_version            => '0.7.0rc10,3.14159-0',
-      :get_dot_version            => '0.7.0rc10',
-      :get_debversion             => '0.7.0-0.1rc10puppetlabs1',
-      :get_rpmversion             => '0.7.0',
+    '0.8.0rc10'                   => {
+      :git_describe_version       => %w{0.8.0rc10},
+      :get_dash_version           => '0.8.0rc10',
+      :get_ips_version            => '0.8.0rc10,3.14159-0',
+      :get_dot_version            => '0.8.0rc10',
+      :get_debversion             => '0.8.0-0.1rc10puppetlabs1',
+      :get_rpmversion             => '0.8.0',
       :get_rpmrelease             => '0.1rc10',
       :is_rc?                     => true,
+      :is_odd?                    => false,
     },
     '0.7.0-rc1'                   => {
       :git_describe_version       => %w{0.7.0 rc1},
@@ -34,26 +36,29 @@ describe "00_utils" do
       :get_rpmversion             => '0.7.0',
       :get_rpmrelease             => '0.1rc1',
       :is_rc?                     => true,
+      :is_odd?                    => true,
     },
-    '0.7.0-rc1-63-ge391f55'       => {
-      :git_describe_version       => %w{0.7.0 rc1 63},
-      :get_dash_version           => '0.7.0-rc1-63',
-      :get_ips_version            => '0.7.0,3.14159-63',
-      :get_dot_version            => '0.7.0.rc1.63',
-      :get_debversion             => '0.7.0-0.1rc1.63puppetlabs1',
-      :get_rpmversion             => '0.7.0',
+    '0.4.0-rc1-63-ge391f55'       => {
+      :git_describe_version       => %w{0.4.0 rc1 63},
+      :get_dash_version           => '0.4.0-rc1-63',
+      :get_ips_version            => '0.4.0,3.14159-63',
+      :get_dot_version            => '0.4.0.rc1.63',
+      :get_debversion             => '0.4.0-0.1rc1.63puppetlabs1',
+      :get_rpmversion             => '0.4.0',
       :get_rpmrelease             => '0.1rc1.63',
       :is_rc?                     => true,
+      :is_odd?                    => false,
     },
-    '0.7.0-rc1-63-ge391f55-dirty' => {
-      :git_describe_version       => %w{0.7.0 rc1 63 dirty},
-      :get_dash_version           => '0.7.0-rc1-63-dirty',
-      :get_ips_version            => '0.7.0,3.14159-63-dirty',
-      :get_dot_version            => '0.7.0.rc1.63.dirty',
-      :get_debversion             => '0.7.0-0.1rc1.63dirtypuppetlabs1',
-      :get_rpmversion             => '0.7.0',
+    '0.6.0-rc1-63-ge391f55-dirty' => {
+      :git_describe_version       => %w{0.6.0 rc1 63 dirty},
+      :get_dash_version           => '0.6.0-rc1-63-dirty',
+      :get_ips_version            => '0.6.0,3.14159-63-dirty',
+      :get_dot_version            => '0.6.0.rc1.63.dirty',
+      :get_debversion             => '0.6.0-0.1rc1.63dirtypuppetlabs1',
+      :get_rpmversion             => '0.6.0',
       :get_rpmrelease             => '0.1rc1.63dirty',
       :is_rc?                     => true,
+      :is_odd?                    => false,
 
     },
     '0.7.0-63-ge391f55'           => {
@@ -65,6 +70,7 @@ describe "00_utils" do
       :get_rpmversion             => '0.7.0.63',
       :get_rpmrelease             => '1',
       :is_rc?                     => false,
+      :is_odd?                    => true,
 
     },
     '0.7.0-63-ge391f55-dirty'     => {
@@ -76,6 +82,7 @@ describe "00_utils" do
       :get_rpmversion             => '0.7.0.63.dirty',
       :get_rpmrelease             => '1',
       :is_rc?                     => false,
+      :is_odd?                    => true,
     },
   }
 

data/ext/packaging/spec/tasks/build_object_spec.rb

@@ -36,11 +36,13 @@ describe Build::BuildInstance do
                   :gem_dependencies,
                   :gem_description,
                   :gem_devel_dependencies,
+                  :gem_development_dependencies,
                   :gem_excludes,
                   :gem_executables,
                   :gem_files,
                   :gem_forge_project,
                   :gem_name,
+                  :gem_platform_dependencies,
                   :gem_rdoc_options,
                   :gem_require_path,
                   :gem_runtime_dependencies,
@@ -62,6 +64,7 @@ describe Build::BuildInstance do
                   :jenkins_packaging_job,
                   :jenkins_repo_path,
                   :metrics,
+                  :metrics_url,
                   :name,
                   :notify,
                   :project,
@@ -84,17 +87,16 @@ describe Build::BuildInstance do
                   :rpmversion,
                   :ref,
                   :sign_tar,
-                  :sles_build_host,
-                  :sles_repo_path,
-                  :sles_repo_host,
-                  :sles_arch_repos,
                   :summary,
                   :tar_excludes,
                   :tar_host,
                   :tarball_path,
                   :team,
+                  :templates,
+                  :update_version_file,
                   :version,
                   :version_file,
+                  :version_strategy,
                   :yum_host,
                   :yum_repo_path]
 

data/ext/packaging/static_artifacts/PackageInfo.plist

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pkg-info followSymLinks="true" minimumSystemVersion="10.6" auth="root"/>
+

data/ext/packaging/tasks/00_utils.rake

@@ -93,7 +93,7 @@ end
 
 def rsync_to *args
   check_tool('rsync')
-  flags = "-rHlv -O --no-perms --no-owner --no-group"
+  flags = "-rHlv -O --no-perms --no-owner --no-group --ignore-existing"
   source  = args[0]
   target  = args[1]
   dest    = args[2]
@@ -228,8 +228,10 @@ end
 
 def load_keychain
   unless @keychain_loaded
-    kill_keychain
-    start_keychain
+    unless ENV['RPM_GPG_AGENT']
+      kill_keychain
+      start_keychain
+    end
     @keychain_loaded = TRUE
   end
 end
@@ -260,7 +262,8 @@ def gpg_sign_file(file)
   gpg ||= find_tool('gpg')
 
   if gpg
-    sh "#{gpg} --armor --detach-sign -u #{@build.gpg_key} #{file}"
+    use_tty = "--no-tty --use-agent" if ENV['RPM_GPG_AGENT']
+    sh "#{gpg} #{use_tty} --armor --detach-sign -u #{@build.gpg_key} #{file}"
   else
     fail "No gpg available. Cannot sign #{file}."
   end
@@ -311,6 +314,7 @@ def git_commit_file(file, message=nil)
 end
 
 def ship_gem(file)
+  check_file("#{ENV['HOME']}/.gem/credentials")
   %x{gem push #{file}}
 end
 
@@ -360,9 +364,9 @@ def rand_string
   rand.to_s.split('.')[1]
 end
 
-def git_bundle(treeish)
-  temp = get_temp
-  appendix = rand_string
+def git_bundle(treeish, appendix=nil, output_dir=nil)
+  temp = output_dir || get_temp
+  appendix ||= rand_string
   sh "git bundle create #{temp}/#{@build.project}-#{@build.version}-#{appendix} #{treeish} --tags"
   cd temp do
     sh "tar -czf #{@build.project}-#{@build.version}-#{appendix}.tar.gz #{@build.project}-#{@build.version}-#{appendix}"
@@ -371,12 +375,14 @@ def git_bundle(treeish)
   "#{temp}/#{@build.project}-#{@build.version}-#{appendix}.tar.gz"
 end
 
-# We take a tar argument for cases where `tar` isn't best, e.g. Solaris
-def remote_bootstrap(host, treeish, tar_cmd=nil)
+# We take a tar argument for cases where `tar` isn't best, e.g. Solaris.  We
+# also take an optional argument of the tarball containing the git bundle to
+# use.
+def remote_bootstrap(host, treeish, tar_cmd=nil, tarball=nil)
   unless tar = tar_cmd
     tar = 'tar'
   end
-  tarball = git_bundle(treeish)
+  tarball ||= git_bundle(treeish)
   tarball_name = File.basename(tarball).gsub('.tar.gz','')
   rsync_to(tarball, host, '/tmp')
   appendix = rand_string
@@ -456,28 +462,62 @@ def deprecate(old_cmd, new_cmd=nil)
   STDOUT.puts
 end
 
-# Determines if this package is an rc package via the version
-# returned by get_dash_version method.
+# Determines if this package is a final package via the
+# selected version_strategy.
+# There are currently two supported version strategies.
+#
+# This method calls down to the version strategy indicated, defaulting to the
+# rc_final strategy. The methods themselves will return false if it is a final
+# release, so their return values are collected and then inverted before being
+# returned.
+def is_final?
+  ret = nil
+  case @build.version_strategy
+    when "rc_final"
+      ret = is_rc?
+    when "odd_even"
+      ret = is_odd?
+    when nil
+      ret = is_rc?
+  end
+  return (! ret)
+end
+
+# the rc_final strategy (default)
 # Assumes version strings in the formats:
 # final:
 # '0.7.0'
 # '0.7.0-63'
 # '0.7.0-63-dirty'
-# rc:
+# development:
 # '0.7.0rc1 (we don't actually use this format anymore, but once did)
 # '0.7.0-rc1'
 # '0.7.0-rc1-63'
 # '0.7.0-rc1-63-dirty'
 def is_rc?
   return TRUE if get_dash_version =~ /^\d+\.\d+\.\d+-*rc\d+/
-  FALSE
+  return FALSE
+end
+
+# the odd_even strategy (mcollective)
+# final:
+# '0.8.0'
+# '1.8.0-63'
+# '0.8.1-63-dirty'
+# development:
+# '0.7.0'
+# '1.7.0-63'
+# '0.7.1-63-dirty'
+def is_odd?
+  return TRUE if get_dash_version.match(/^\d+\.(\d+)\.\d+/)[1].to_i.odd?
+  return FALSE
 end
 
 # Utility method to return the dist method if this is a redhat box. We use this
 # in rpm packaging to define a dist macro, and we use it in the pl:fetch task
 # to disable ssl checking for redhat 5 because it has a certs bundle so old by
 # default that it's useless for our purposes.
-def el_version()
+def el_version
   if File.exists?('/etc/fedora-release')
     nil
   elsif File.exists?('/etc/redhat-release')
@@ -578,3 +618,39 @@ def escape_html(uri)
   require 'cgi'
   CGI.escapeHTML(uri)
 end
+
+# Add a parameter to a given uri. If we were sane we'd use
+# encode_www_form(params) of URI, but because we're not, because that will http
+# encode it, which isn't what we want since we're require the encoding provided
+# by escapeHTML of CGI, since this is being transfered in the xml of a jenkins
+# job via curl and DEAR JEEBUS WHAT HAVE WE DONE.
+def add_param_to_uri(uri, param)
+  require 'uri'
+  uri = URI.parse(uri)
+  uri.query = [uri.query, param].compact.join('&')
+  uri.to_s
+end
+
+# Remotely set the immutable bit on a list of files
+#
+def remote_set_immutable(host, files)
+  remote_ssh_cmd(host, "sudo chattr +i #{files.join(" ")}")
+end
+
+# ex combines the behavior of `%x{cmd}` and rake's `sh "cmd"`. `%x{cmd}` has
+# the benefit of returning the standard out of an executed command, enabling us
+# to query the file system, e.g. `contents = %x{ls}`. The drawback to `%x{cmd}`
+# is that on failure of a command (something returned non-zero) the return of
+# `%x{cmd}` is just an empty string. As such, we can't know if we succeeded.
+# Rake's `sh "cmd"`, on the other hand, will raise a RuntimeError if a command
+# does not return 0, but doesn't return any of the stdout from the command -
+# only true or false depending on its success or failure. With `ex(cmd)` we
+# purport to both return the results of the command execution (ala `%x{cmd}`)
+# while also raising an exception if a command does not succeed (ala `sh "cmd"`).
+def ex(command)
+  ret = %x[#{command}]
+  unless $?.success?
+    raise RuntimeError
+  end
+  ret
+end