beaker 3.35.0 → 3.36.0

data/docs/how_to/upgrade_from_2_to_3.md

@@ -1,80 +1,40 @@
 # How To Upgrade from 2.y to 3.0
 
-This is a guide detailing all the issues to be aware of, and to help people make
-any changes that you might need to move from beaker 2.y to 3.0. To test out
-beaker 3.0.0, we recommend implementing the strategy outlined [here](test_arbitrary_beaker_versions.md)
-to ensure this new major release does not break your existing testing.
+This is a guide detailing all the issues to be aware of, and to help people make any changes that you might need to move from beaker 2.y to 3.0. To test out beaker 3.0.0, we recommend implementing the strategy outlined [here](test_arbitrary_beaker_versions.md) to ensure this new major release does not break your existing testing.
 
 ## Ruby version 1.9.3 no longer supported
 
-Official support for 1.9.3 has been eol'd since Feb 2015; the beaker 3.0.0 release
-drops support for ruby 1.9.3 and will not install with ruby 1.9.3. We suggest using
-ruby >= 2.2.5, as that is the version we currently test and support at Puppet.
+Official support for 1.9.3 has been eol'd since Feb 2015; the beaker 3.0.0 release drops support for ruby 1.9.3 and will not install with ruby 1.9.3. We suggest using ruby >= 2.2.5, as that is the version we currently test and support at Puppet.
 
 ## Locally Cached Files
 
 This is a change of the `:cache_files_locally` preset from `true` to `false`.
 
-At this time, the `:cache_files_locally` setting only affects the
-[`fetch_http_file` method](https://github.com/puppetlabs/beaker/blob/master/lib/beaker/dsl/helpers/web_helpers.rb#L44).
-This is an internal method used in both Puppet Enterprise (PE) and Open Source
-Puppet install helpers to download files from the internet to the Beaker
-coordinator.
-
-If a file with the same destination name already exists on the coordinator,
-Beaker would not fetch the file and use the cached copy instead. In general,
-this wasn't a big problem because we typically have our version numbers in our
-install artifacts, so file name matching is enough. In our Windows MSI
-installers, however, we would many times not have versions built into the file
-name. Since that's the case, you could get an old version installed because it
-was already on your coordinator filesystem. The `:cache_files_locally` setting
-allows you to set whether you want to use a local file cache, or get fresh
-installers every time. This setting is now set to false, and will get installers
-from the online source every time.
-
-If you'd like to keep this setting the way it was in 2.y, then just set the
-global option `:cache_files_locally` to `false`. Checkout the
-[Argument Processing and Precedence](../concepts/argument_processing_and_precedence.md)
-doc for info on how to do this.
+At this time, the `:cache_files_locally` setting only affects the [`fetch_http_file` method](https://github.com/puppetlabs/beaker/blob/master/lib/beaker/dsl/helpers/web_helpers.rb#L44). This is an internal method used in both Puppet Enterprise (PE) and Open Source Puppet install helpers to download files from the internet to the Beaker coordinator.
+
+If a file with the same destination name already exists on the coordinator, Beaker would not fetch the file and use the cached copy instead. In general, this wasn't a big problem because we typically have our version numbers in our install artifacts, so file name matching is enough. In our Windows MSI installers, however, we would many times not have versions built into the file name. Since that's the case, you could get an old version installed because it was already on your coordinator filesystem. The `:cache_files_locally` setting allows you to set whether you want to use a local file cache, or get fresh installers every time. This setting is now set to false, and will get installers from the online source every time.
+
+If you'd like to keep this setting the way it was in 2.y, then just set the global option `:cache_files_locally` to `false`. Checkout the [Argument Processing and Precedence](../concepts/argument_processing_and_precedence.md) doc for info on how to do this.
 
 ## EPEL package update
 
-In beaker < 3.0.0, the epel package names had hardcoded defaults listed in the
-presets default; in beaker >= 3.0.0, beaker utilizes the `release-latest` file
-provided on epel mirrors for el versions 5, 6, and 7. Since only the latest epel
-packages are available on epel mirrors, beaker only supports installation of
-that latest version.
+In beaker < 3.0.0, the epel package names had hardcoded defaults listed in the presets default; in beaker >= 3.0.0, beaker utilizes the `release-latest` file provided on epel mirrors for el versions 5, 6, and 7. Since only the latest epel packages are available on epel mirrors, beaker only supports installation of that latest version.
 
 ## Solaris and AIX Hypervisors removed
 
-Special cased hypervisor support for Solaris and AIX have been removed in favor
-of a `hypervisor=none` workflow where the provisioning of SUTs is handled separately
-outside of beaker itself. Solaris and AIX are still of course supported as `platform`
-strings; only these special-cased hypervisors have been removed.
+Special cased hypervisor support for Solaris and AIX have been removed in favor of a `hypervisor=none` workflow where the provisioning of SUTs is handled separately outside of beaker itself. Solaris and AIX are still of course supported as `platform` strings; only these special-cased hypervisors have been removed.
 
 ## Environment Variable DSL Methods
 
-In [BKR-914](https://tickets.puppetlabs.com/browse/BKR-914) we fixed our host
-methods that deal with environment variables (
-[#add_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#add_env_var-instance_method),
-[#get_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#get_env_var-instance_method),
-and
-[#clear_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#clear_env_var-instance_method)).
+In [BKR-914](https://tickets.puppetlabs.com/browse/BKR-914) we fixed our host methods that deal with environment variables ( [#add_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#add_env_var-instance_method), [#get_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#get_env_var-instance_method), and [#clear_env_var](http://www.rubydoc.info/github/puppetlabs/beaker/Unix/Exec#clear_env_var-instance_method)).
 
-Before, these methods used regular expressions that were too loose. This means
-that in an example of a call like `get_env_var('abc')`, the environment variables
-`abc=123`, `xx_abc_xx=123`, and `123=abc` would all be matched, where the intent
-is to get `abc=123` alone. From Beaker 3.0 forward, this will be the case.
+Before, these methods used regular expressions that were too loose. This means that in an example of a call like `get_env_var('abc')`, the environment variables `abc=123`, `xx_abc_xx=123`, and `123=abc` would all be matched, where the intent is to get `abc=123` alone. From Beaker 3.0 forward, this will be the case.
 
 ## beaker-pe Import Changes
 
-Starting in beaker 3.0, there is no explicit beaker-pe requirement in beaker. This
-separates the two, meaning that you'll have to explicitly require beaker-pe if you
-do need it in your testing. And if you don't need it, you won't get it, limiting
-your dependencies & exposure to unnecessary code.
+Starting in beaker 3.0, there is no explicit beaker-pe requirement in beaker. This separates the two, meaning that you'll have to explicitly require beaker-pe if you do need it in your testing. And if you don't need it, you won't get it, limiting your dependencies & exposure to unnecessary code.
 
-Luckily, if you do need it, this shouldn't be hard to update. These are the steps
-needed to use beaker-pe with beaker 3.0:
+Luckily, if you do need it, this shouldn't be hard to update. These are the steps needed to use beaker-pe with beaker 3.0:
 
 1. put a dependency on beaker-pe in your Gemfile as a sibling to your beaker
   requirement (make sure beaker-pe is >= 1.0)

data/docs/how_to/use_hocon_helpers.md

@@ -1,37 +1,19 @@
-# How-to Use Hocon Helpers
+# How to Use Hocon Helpers
 
-Beaker provides a few convenience methods to help you use the
-[HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md)
-configuration file format in your testing. This doc will give you an overview of
-what each method does, but if you'd like more in-depth information, please
-checkout our
-[Hocon Helpers Rubydocs](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HoconHelpers).
+Beaker provides a few convenience methods to help you use the [HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md) configuration file format in your testing. This doc will give you an overview of what each method does, but if you'd like more in-depth information, please checkout our [Hocon Helpers Rubydocs](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HoconHelpers).
 
-# #hocon_file_read_on
+## hocon_file_read_on
 
-If you'd just like to read the contents of a HOCON file from a System Under Test
-(SUT), this is the method for you. Note that you will get back a
-[ConfigValueFactory object](https://github.com/puppetlabs/ruby-hocon#basic-usage)
-like in the other helper methods here.
+If you'd just like to read the contents of a HOCON file from a System Under Test (SUT), this is the method for you. Note that you will get back a [ConfigValueFactory object](https://github.com/puppetlabs/ruby-hocon#basic-usage) like in the other helper methods here.
 
-# #hocon_file_edit_in_place_on
+## hocon_file_edit_in_place_on
 
-This method is specifically for editing a file on a SUT and saving it in-place,
-meaning it'll save your changes in the place of the original file you read from.
+This method is specifically for editing a file on a SUT and saving it in-place, meaning it'll save your changes in the place of the original file you read from.
 
-The special thing to take note of here is that the Proc you pass to this method
-will need to return the doc that you'd like saved in order for saving to work as
-specified.
+The special thing to take note of here is that the Proc you pass to this method will need to return the doc that you'd like saved in order for saving to work as specified.
 
-# #hocon_file_edit_on
+## hocon_file_edit_on
 
-This method is our generic open-ended method for editing a file from a SUT. This
-is the most flexible method, doing nothing but providing you with the contents
-of the file to edit yourself.
+This method is our generic open-ended method for editing a file from a SUT. This is the most flexible method, doing nothing but providing you with the contents of the file to edit yourself.
 
-This does not save the file edited. Our recommendation is to use the
-[`create_remote_file` method](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HostHelpers#create_remote_file-instance_method),
-as shown in the
-[Rubydocs example](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HoconHelpers#hocon_file_edit_on-instance_method)
-if you'd like to save. This allows us to have more flexibility to do things such
-as moving the edited file to back up or version your changes.
+This does not save the file edited. Our recommendation is to use the [`create_remote_file` method](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HostHelpers#create_remote_file-instance_method), as shown in the [Rubydocs example](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HoconHelpers#hocon_file_edit_on-instance_method) if you'd like to save. This allows us to have more flexibility to do things such as moving the edited file to back up or version your changes.

data/docs/how_to/use_user_password_authentication.md

@@ -1,7 +1,8 @@
-By default Beaker connects to hosts using public key authentication, but that may not be correct method for your particular testing set up.  To have beaker connect to a host using a username/password combination edit your hosts configuration file.  You will need to create a new ssh hash to be used for logging into your SUT that includes (at least) entries for _user_, _password_, and _auth_method_.  You may also include any additional supported [Net::SSH Options](http://net-ssh.github.io/ssh/v1/chapter-2.html#s3).
+By default Beaker connects to hosts using public key authentication, but that may not be correct method for your particular testing set up. To have beaker connect to a host using a username/password combination edit your hosts configuration file. You will need to create a new ssh hash to be used for logging into your SUT that includes (at least) entries for `user`, `password`, and `auth_method`. You may also include any additional supported [Net::SSH Options](http://net-ssh.github.io/ssh/v1/chapter-2.html#s3).
 
 ## Example 1: Use 'password' authentication
-```
+
+```yaml
 HOSTS:
   pe-centos6:
     roles:
@@ -11,10 +12,10 @@ HOSTS:
       - database
       - myrole
     platform: el-6-i386
-    snapshot : clean-w-keys
-    hypervisor : fusion
+    snapshot: clean-w-keys
+    hypervisor: fusion
     ssh:
-      password : anode
+      password: anode
       user: anode
       auth_methods:
         - password
@@ -30,8 +31,10 @@ Attempting ssh connection to pe-centos6, user: anode, opts: {:config=>false, :ve
 _/snip_
 
 ## Example 2: Use a list of authentication methods
-If you want to try a sequence of authentication techniques that fall through on failure simply include them (in their desired order) in your list of _auth_methods_.  If one of your methods is user/password be warned, after a failure Net::SSH will attempt keyboard-interactive password entry - if you do not want this behavior add _number_of_password_prompts: 0_.
-```
+
+If you want to try a sequence of authentication techniques that fall through on failure simply include them (in their desired order) in your list of `auth_methods`. If one of your methods is user/password be warned, after a failure Net::SSH will attempt keyboard-interactive password entry - if you do not want this behavior add `number_of_password_prompts: 0`.
+
+```yaml
 HOSTS:
   pe-centos6:
     roles:
@@ -41,13 +44,13 @@ HOSTS:
       - database
       - myrole
     platform: el-6-i386
-    snapshot : clean-w-keys
-    hypervisor : fusion
+    snapshot: clean-w-keys
+    hypervisor: fusion
 CONFIG:
   ssh:
     auth_methods:
       - password
       - publickey
     number_of_password_prompts: 0
-    password : wootwoot
+    password: wootwoot
 ```

data/docs/how_to/write_a_beaker_test_for_a_module.md

@@ -1,11 +1,15 @@
 # Beaker for Modules
+
 ## Read the Beaker Docs
 
-[Beaker How To](../tutorials/how_to_beaker.md)
-[Beaker DSL API](http://rubydoc.info/github/puppetlabs/beaker/frames)
+- [Beaker How To](../tutorials/how_to_beaker.md)
+
+- [Beaker DSL API](http://rubydoc.info/github/puppetlabs/beaker/frames)
 
 ## Understand the Difference Between beaker and beaker-rspec
+
 [beaker vs. beaker-rspec](../concepts/beaker_vs_beaker_rspec.md)
 
 ## beaker-rspec Details
+
 See the [beaker-rspec README](https://github.com/puppetlabs/beaker-rspec/blob/master/README.md) for details on how to use beaker-rspec with modules.

data/docs/tutorials/README.md

@@ -1,82 +1,41 @@
 # Tutorials
 
-This doc is here to help you get acquainted with beaker
-and how we run our acceptance tests at Puppet. We'll go
-over the purpose of each doc, giving you an idea of when
-you might need each one. The list has been organized as
-a learning guide for someone new to using beaker, so be
-aware of that if you're just dipping into a topic.
-
-For more high level & motivation topics, checkout our
-[concepts docs](../concepts). If you're looking for
-more details on a topic than what is provided in the
-tutorials, checkout our [how to docs](../how_to). And
-if you'd like API level details, feel free to skip on
-over to our
-[Rubydocs](http://www.rubydoc.info/github/puppetlabs/beaker/frames).
-And without further pre-amble, we beaker!
+This doc is here to help you get acquainted with beaker and how we run our acceptance tests at Puppet. We'll go over the purpose of each doc, giving you an idea of when you might need each one. The list has been organized as a learning guide for someone new to using beaker, so be aware of that if you're just dipping into a topic.
+
+For more high level & motivation topics, checkout our [concepts docs](../concepts). If you're looking for more details on a topic than what is provided in the tutorials, checkout our [how to docs](../how_to). And if you'd like API level details, feel free to skip on over to our [Rubydocs](http://www.rubydoc.info/github/puppetlabs/beaker/frames). And without further pre-amble, we beaker!
 
 ## Installation
 
-If you haven't installed beaker yet, your guide to doing
-so can be found [here](installation.md).
+If you haven't installed beaker yet, your guide to doing so can be found [here](installation.md).
 
 ## Quick Start
 
-As a completely new beaker user, the
-[quick start rake tasks doc](quick_start_rake_tasks.md)
-will take you through getting beaker running for the
-first time.
+As a completely new beaker user, the [quick start rake tasks doc](quick_start_rake_tasks.md) will take you through getting beaker running for the first time.
 
 ## OK, We're Running. Now What?
 
-This is where things get interesting. There are a
-number of directions you can go, based on your needs.
-Here's a list of the common directions people take at
-this point.
+This is where things get interesting. There are a number of directions you can go, based on your needs. Here's a list of the common directions people take at this point.
 
 ### Test Writing
 
-Most people reading this doc are in Quality orgs, or
-are developers who need to get some testing done for
-their current work. If getting a particular bit of
-testing done is your next step, this is the direction
-for you.
+Most people reading this doc are in Quality orgs, or are developers who need to get some testing done for their current work. If getting a particular bit of testing done is your next step, this is the direction for you.
 
-Checkout our [let's write a test](lets_write_a_test.md)
-to start with test writing!
+Checkout our [let's write a test](lets_write_a_test.md) to start with test writing!
 
 ### Running Beaker Itself
 
-For the quick start guide, we resorted to using rake
-tasks to get beaker running quickly and easily. In
-the real world, people need much more customization
-out of their testing environments. One of the main
-ways people provide these options is through
-command line arguments.
+For the quick start guide, we resorted to using rake tasks to get beaker running quickly and easily. In the real world, people need much more customization out of their testing environments. One of the main ways people provide these options is through command line arguments.
 
-If you want to find out more about running beaker
-itself, checkout [the command line](the_command_line.md).
+If you want to find out more about running beaker itself, checkout [the command line](the_command_line.md).
 
 ### Environment Details
 
-If you don't need to get your tests running _anywhere_,
-but need them on a ton of Operating Systems (OSes),
-then your next stop is setting up your test environment.
+If you don't need to get your tests running _anywhere_, but need them on a ton of Operating Systems (OSes), then your next stop is setting up your test environment.
 
-Our
-[creating a test environment doc](creating_a_test_environment.md)
-is the next spot for you!
+Our [creating a test environment doc](creating_a_test_environment.md) is the next spot for you!
 
 ### High Level Execution Details
 
-For a higher level look at what happens during beaker
-execution, which we call a _run_, checkout our
-[test run doc](test_run.md). A _run_ is an entire
-beaker execution cycle, from when the command is run
-until beaker exits.
+For a higher level look at what happens during beaker execution, which we call a _run_, checkout our [test run doc](test_run.md). A _run_ is an entire beaker execution cycle, from when the command is run until beaker exits.
 
-As one phase of a test run, the test suites are executed.
-To get more information about the test suites that
-are available, and how you configure them, you can
-checkout our [test suites doc](test_suites.md).
+As one phase of a test run, the test suites are executed. To get more information about the test suites that are available, and how you configure them, you can check out our [test suites doc](test_suites.md).

data/docs/tutorials/creating_a_test_environment.md

@@ -1,36 +1,37 @@
-Hosts/Nodes/SUTs are defined in the --hosts (--config) file in Yaml format.
-This file defines each node in the test configuration. The file can be saved
-anywhere and used with `beaker --hosts yourhost.yaml`
-(see [The Command Line](the_command_line.md) for more info).
+Hosts/Nodes/SUTs are defined in the --hosts (--config) file in Yaml format. This file defines each node in the test configuration. The file can be saved anywhere and used with `beaker --hosts yourhost.yaml` (see [The Command Line](the_command_line.md) for more info).
 
 Example hosts file:
 
-    HOSTS:
-      ubuntu-1404-x64-master:
-        roles:
-          - master
-          - agent
-          - dashboard
-          - database
-        platform: ubuntu-1404-x86_64
-        hypervisor: vagrant
-        box: puppetlabs/ubuntu-14.04-64-nocm
-        box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
-        ip: 192.168.20.20
-      ubuntu-1404-x64-agent:
-        roles:
-          - agent
-        platform: ubuntu-1404-x86_64
-        hypervisor: vagrant
-        box: puppetlabs/ubuntu-14.04-64-nocm
-        box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
-        ip: 192.168.21.21
-    CONFIG:
-      nfs_server: none
-      consoleport: 443
-
-## Host Requirements ##
+```yaml
+  HOSTS:
+    ubuntu-1404-x64-master:
+      roles:
+        - master
+        - agent
+        - dashboard
+        - database
+      platform: ubuntu-1404-x86_64
+      hypervisor: vagrant
+      box: puppetlabs/ubuntu-14.04-64-nocm
+      box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
+      ip: 192.168.20.20
+    ubuntu-1404-x64-agent:
+      roles:
+        - agent
+      platform: ubuntu-1404-x86_64
+      hypervisor: vagrant
+      box: puppetlabs/ubuntu-14.04-64-nocm
+      box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
+      ip: 192.168.21.21
+  CONFIG:
+    nfs_server: none
+    consoleport: 443
+```
+
+## Host Requirements
+
 Hosts, or SUTs (Systems Under Test), must meet the following requirements:
+
 * The SUT will need a properly configured network, hosts will need to be able to reach each other by hostname.
 * On the SUT, you must configure passwordless SSH authentication for the root user.
 * The SUT must have the `ntpdate` binary installed.
@@ -38,34 +39,28 @@ Hosts, or SUTs (Systems Under Test), must meet the following requirements:
 * On Windows, `Cygwin` must be installed (with `curl`, `sshd`, `bash`) and the necessary windows gems (`sys-admin`, `win32-dir`, etc).
 * FOSS install: you must have `git`, `ruby`, and `rdoc` installed on your SUT.
 
-## Required Host Settings ##
+## Required Host Settings
+
 To properly define a host you must provide:
 
-* name
-  * The string identifying this host.
-* platform
-  * One of the Beaker supported platforms.
+* name: The string identifying this host.
+* platform: One of the Beaker supported platforms.
+
+## Optional Host Settings
 
-## Optional Host Settings ##
 Additionally, Beaker supports the following host options:
 
-* ip
-  * The IP address of the SUT.
-* hypervisor
-  * One of `docker`, `solaris`, `ec2`, `vsphere`, `fusion`, `aix`, `vcloud` or `vagrant`.
+* ip: The IP address of the SUT.
+* hypervisor: One of `docker`, `solaris`, `ec2`, `vsphere`, `fusion`, `aix`, `vcloud` or `vagrant`.
   * Additional settings may be required depending on the selected hypervisor (ie, template, box, box_url, etc).  Check the documentation below for your hypervisor for details.
-* snapshot
-  * The name of the snapshot to revert to before testing.
-* roles
-  * The 'job' of this host, an array of `master`, `agent`, `frictionless`, `dashboard`, `database`, `default` or any user-defined string.
-* pe_dir
-  * The directory where PE builds are located, may be local directory or a URL.
-* pe_ver
-  * The version number of PE to install.
-* vagrant_memsize
-  * The memory size (in MB) for this host
-
-## Supported Platforms ##
+* snapshot: The name of the snapshot to revert to before testing.
+* roles: The 'job' of this host, an array of `master`, `agent`, `frictionless`, `dashboard`, `database`, `default` or any user-defined string.
+* pe_dir: The directory where PE builds are located, may be local directory or a URL.
+* pe_ver: The version number of PE to install.
+* vagrant_memsize: The memory size (in MB) for this host
+
+## Supported Platforms
+
 Beaker depends upon each host in the configuration file having a platform type that is correctly formatted and supported.  The platform is used to determine how various operations are carried out internally (such as installing packages using the correct package manager for the given operating system).
 
 The platform's format is `/^OSFAMILY-VERSION-ARCH.*$/` where `OSFAMILY` is one of:
@@ -83,4 +78,4 @@ The platform's format is `/^OSFAMILY-VERSION-ARCH.*$/` where `OSFAMILY` is one o
 
 `VERSION`'s format is not enforced, but should reflect the `OSFAMILY` selected (ie, ubuntu-1204-i386-master, scientific-6-i386-agent, etc).  `ARCH`'s format is also not enforced, but should be appropriate to the `OSFAMILY` selected (ie, ubuntu-1204-i386-master, sles-11-x86_64-master, debian-7-amd64-master, etc).
 
-## [Supported Virtualization Providers](../how_to/hypervisors/README.md#external-hypervisors) ##
+## [Supported Virtualization Providers](../how_to/hypervisors/README.md#external-hypervisors)

data/docs/tutorials/installation.md

@@ -11,17 +11,26 @@ In most cases, beaker is running on a system separate from the SUT; we will comm
 
 On a Debian or Ubuntu system you can install these using the command
 
-    sudo apt-get install ruby-dev libxml2-dev libxslt1-dev g++ zlib1g-dev
+```console
+  $ sudo apt-get install ruby-dev libxml2-dev libxslt1-dev g++ zlib1g-dev
+```
 
 On an EL or Fedora system use:
 
-    sudo yum install make gcc gcc-c++ libxml2-devel libxslt-devel ruby-devel
+```console
+  $ sudo yum install make gcc gcc-c++ libxml2-devel libxslt-devel ruby-devel
+```
 
 ## Installing Beaker
+
+These instructions apply to installing Beaker for use; to set up a development environment for Beaker itself, [see below](#for-development).
+
 ### From Gem (Preferred)
 
-    $ gem install beaker
-    $ beaker --help
+```console
+  $ gem install beaker
+  $ beaker --help
+```
 
 ### From Latest Git
 
@@ -29,26 +38,30 @@ If you need the latest and greatest (and mostly likely broken/untested/no warran
 
 * Uses <a href = "http://bundler.io/">bundler</a>
 
-<!-- end of list -->
-    $ git clone https://github.com/puppetlabs/beaker
-    $ cd beaker
-    $ bundle install
-    $ bundle exec beaker --help
+```console
+  $ git clone https://github.com/puppetlabs/beaker
+  $ cd beaker
+  $ bundle install
+  $ bundle exec beaker --help
+```
 
 ### From Latest Git, As Installed Gem
 
 If you need the latest and greatest, but prefer to work from gem instead of through bundler.
 
+```console
     $ gem uninstall beaker
     $ git clone https://github.com/puppetlabs/beaker
     $ cd beaker
     $ gem build beaker.gemspec
     $ gem install ./beaker-*.gem
+```
 
 ### Special Case Installation
 
 The beaker gem can be built and installed in the context of the current test suite by adding the github repos as the source in the Gemspec file (see <a href = "http://bundler.io/git.html">bundler git documentation</a>).
 
+```ruby
     source 'https://rubygems.org'
     group :testing do
       gem 'cucumber', '~> 1.3.6'
@@ -57,18 +70,41 @@ The beaker gem can be built and installed in the context of the current test sui
       gem 'chromedriver2-helper'
       gem 'beaker', :github => 'puppetlabs/beaker', :branch => 'master', :ref => 'fffe7'
     end
+```
+
+## For Development
+
+If you intend to make changes to Beaker itself, follow these instructions.
+
+### Recommended Tools
+
+It may be necessary to test Beaker against multiple versions of Ruby. The maintainers use [`rbenv`](https://github.com/rbenv/rbenv) to manage multiple Ruby versions; you can install it with Homebrew. You'll also want [`rbenv-bundler`](https://github.com/carsomyr/rbenv-bundler) to keep Gem dependencies from conflicting.
+
+### Setup for Development
+
+While most users will use Beaker as a Gem installed from some repository, you will need a live repo to work with. Here's how to configure Beaker and its dependencies so you can start contributing:
+
+* Clone your fork of Beaker
+* Install Beaker's dependencies into `vendor/bundle`:
+  ```console
+    $ cd beaker/
+    $ bundle install --path vendor/bundle
+  ```
+  * Installing the dependencies globally ~~may~~ *will probably* cause conflicts and is not recommended.
+  * Please use `vendor/bundle`, not `_vendor` or `.vendor`.
+* Test your new environment by seeing if the spec tests pass (beaker/master is maintained in an always-passing state):
+  ```console
+    $ rake test:spec # assuming you have rbenv-bundler
+    # or
+    $ bundle exec rake test:spec # if you're *sure* your dependencies are tidy
+  ```
+
+### Contributing
+
+Contributions to Beaker are welcomed, see [CONTRIBUTING.md](/CONTRIBUTING.md)) for instructions.
 
 ## Ruby Version
 
-In moving to beaker 3.0, we added in a hard requirement that a
-beaker test writer be using Ruby 2.2.5 or higher. Since Puppet
-has versions that support earlier versions of Ruby, this made
-writing tests more difficult than it needed to be.
-
-In order to make this easier, in beaker 3.13.0 we've relaxed
-this requirement to Ruby 2.1.8. Note that the beaker team does
-not internally test Ruby versions below 2.2.5, and that if bugs
-are submitted that are found to be specific to versions below
-2.2.5, they will not be worked on by the beaker team. This
-doesn't mean we won't merge fixes to bugs that are specific to
-those versions that are submitted by the community, however.
+In moving to beaker 3.0, we added in a hard requirement that a beaker test writer be using Ruby 2.2.5 or higher. Since Puppet has versions that support earlier versions of Ruby, this made writing tests more difficult than it needed to be.
+
+In order to make this easier, in beaker 3.13.0 we've relaxed this requirement to Ruby 2.1.8. Note that the beaker team does not internally test Ruby versions below 2.2.5, and that if bugs are submitted that are found to be specific to versions below 2.2.5, they will not be worked on by the beaker team. This doesn't mean we won't merge fixes to bugs that are specific to those versions that are submitted by the community, however.