runbook 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fe4b7ea15d7d74edf1a660fda55c9f8360a16f7e5032acadc427039240b9cf6
-  data.tar.gz: c72e2c91cd75587c87ed4b9e5921e1be050ea6466c59e1d903fefcf7f6770bfd
+  metadata.gz: 3cb2a40c659a212a9fda6d78d1e94b07ba51625896cd6e4f4a4b6668e42bbc4e
+  data.tar.gz: 065708ff0b3bd93dfdcc35b60730138053e64af9e78768176282f5dc59236b66
 SHA512:
-  metadata.gz: 129f995881810339793273c74d00a872b62cd865f8712fe7db063356c95bdae7f090537d244383b00fbf81cf2de8555e59627248b9e4a6284320aa9594508ef1
-  data.tar.gz: b1c2ef5526b2225d02a246c2d4f5d8e657c599ab04faf96f192084ea4f11d61863f455abc91136a17174dd7645f1112231fa7614ed83862d4444debbc0d2ca07
+  metadata.gz: 87559cf0bee8e17052a2639033a96481fba11963e50c596f138e64fc72b54328288202bfbe3576da6417eada36f219123ba54d726ab0cc6b28176f31552d21ae
+  data.tar.gz: a0b414a4f0b8fa499cc46362d03d2dfb814cf65a46decbd796ffc45e7ecbd0f68db7a2a89168a3ace032814893ef649fa3a1d36982315f548688f4ce7e470b3c

data/.travis.yml

@@ -2,4 +2,8 @@ sudo: false
 language: ruby
 rvm:
   - 2.2.3
+  - 2.2.10
+  - 2.4.6
+  - 2.5.5
+  - 2.6.3
 before_install: gem install bundler -v 1.15.4

data/CHANGELOG.md

@@ -4,6 +4,17 @@ This log maintains a list of all substantive changes to Runbook. The log include
 
 ## master
 
+## `v0.14.0` (2019-08-15)
+
+### Fixes:
+
+* Relax gem dependencies to be compatible with gems up to the next major version
+
+### New Features
+
+* Alias `install` cli command to `init`
+* Add `Runbook.config` alias for `Runbook.configuration`
+
 ## `v0.13.0` (2019-07-10)
 
 ### Potentially Breaking Changes:

data/README.md

@@ -1,6 +1,9 @@
 # Runbook
 
 [![Gem Version](https://badge.fury.io/rb/runbook.svg)](https://badge.fury.io/rb/runbook)
+[![Build Status](https://travis-ci.org/braintree/runbook.svg?branch=master)](https://travis-ci.org/braintree/runbook)
+
+_See our [blog post](https://medium.com/braintree-product-technology/https-medium-com-braintree-product-technology-runbook-be6f072cfc0d) for the philosophy behind Runbook and an overview of its features._
 
 Runbook provides a DSL for specifying a series of steps to execute an operation. Once your runbook is specified, you can use it to generate a formatted representation of the book or to execute the runbook interactively. For example, you can export your runbook to markdown or use the same runbook to execute commands on remote servers.
 
@@ -26,7 +29,7 @@ Lastly, Runbook provides an extendable interface for augmenting the DSL and defi
 * **Dynamic Control Flow** - Runbooks can start execution at any step and can skip steps based on user input.
 * **Resumable** - Runbooks save their state at each step. If your runbook encounters an error, you can resume your runbook at the previous step after addressing the error.
 * **Noop and Auto Modes** - Runbooks can be executed in noop mode. This allows you to see what a runbook will do before it executes. Runbooks can be run in auto mode to eliminate the need for human interaction.
-* **Execution Lifecycle Hooks** - Runbook provides before, after, around hooks to augment its execution behavior.
+* **Execution Lifecycle Hooks** - Runbook provides before, after, and around hooks to augment its execution behavior.
 * **Tmux Integration** - Runbook integrates with [tmux](https://github.com/tmux/tmux). You can define terminal pane layouts and send commands to terminal panes.
 * **Generators** - Runbook provides commands to generate runbooks, extensions, and runbook projects. You can define your own generators for easy, customized runbook creation.
 * **Extendable DSL** - Runbook's DSL is designed to be extendable. You can extend its DSL to add your own behavior.
@@ -107,9 +110,9 @@ Install the Runbook gem:
 
     $ bundle install
 
-Install Runbook into your project:
+Initialize Runbook in your project:
 
-    $ bundle exec runbook install
+    $ bundle exec runbook init
 
 ## Contents
 
@@ -137,38 +140,40 @@ Install Runbook into your project:
       * [1.1.2.15 Wait](#wait)
       * [1.1.2.16 Tmux Layouts](#tmux-layouts)
     * [1.1.3 Setters](#setters)
-* [2. Configuration](#configuration)
-  * [2.1 Configuration Files](#configuration-files)
-* [3. Working With Runbooks](#working-with-runbooks)
-  * [3.1 From Within Your Project](#from-within-your-project)
-  * [3.2 Via The Command Line](#via-the-command-line)
-  * [3.3 Self-executable](#self-executable)
+* [2. Working With Runbooks](#working-with-runbooks)
+  * [2.1 Via The Command Line](#via-the-command-line)
+  * [2.2 From Within Your Project](#from-within-your-project)
+  * [2.3 Self-executable](#self-executable)
+* [3. Configuration](#configuration)
+  * [3.1 Configuration Files](#configuration-files)
 * [4. Best Practices](#best-practices)
   * [4.1 Iterative Automation](#iterative-automation)
   * [4.2 Parameterizing Runbooks](#parameterizing-runbooks)
-  * [4.3 Execution Best Practices](#execution-best-practices)
-  * [4.4 Composing Runbooks](#composing-runbooks)
-  * [4.5 Deep Nesting](#deep-nesting)
-  * [4.6 Load Vs. Eval](#load-vs-eval)
-  * [4.7 Passing State](#passing-state)
+  * [4.3 Passing State](#passing-state)
+  * [4.4 Execution Best Practices](#execution-best-practices)
+  * [4.5 Remote Command Execution](#remote-command-execution)
+  * [4.6 Composing Runbooks](#composing-runbooks)
+  * [4.7 Deep Nesting](#deep-nesting)
+  * [4.8 Load Vs. Eval](#load-vs-eval)
 * [5. Generators](#generators)
   * [5.1 Predefined Generators](#predefined-generators)
   * [5.2 Custom Generators](#custom-generators)
 * [6. Extending Runbook](#extending-runbook)
-  * [6.1 Adding Runs and Views](#adding-runs-and-views)
-  * [6.2 DSL Extensions](#dsl-extensions)
-  * [6.3 Adding New Statements](#adding-new-statements)
-  * [6.4 Adding Run and View Functionality](#adding-run-and-view-functionality)
+  * [6.1 Adding New Statements](#adding-new-statements)
+  * [6.2 Adding Run and View Functionality](#adding-run-and-view-functionality)
+  * [6.3 DSL Extensions](#dsl-extensions)
+  * [6.4 Adding Runs and Views](#adding-runs-and-views)
   * [6.5 Augmenting Functionality With Hooks](#augmenting-functionality-with-hooks)
   * [6.6 Adding New Run Behaviors](#adding-new-run-behaviors)
   * [6.7 Adding to Runbook's Run Metadata](#adding-to-runbooks-run-metadata)
   * [6.8 Adding to Runbook's Configuration](#adding-to-runbooks-configuration)
-* [7. Known Issues](#known-issues)
-* [8. Development](#development)
-* [9. Contributing](#contributing)
-* [10. Feature Requests](#feature-requests)
-* [11. License](#license)
-* [12. Code of Conduct](#code-of-conduct)
+* [7. Testing](#testing)
+* [8. Known Issues](#known-issues)
+* [9. Development](#development)
+* [10. Contributing](#contributing)
+* [11. Feature Requests](#feature-requests)
+* [12. License](#license)
+* [13. Code of Conduct](#code-of-conduct)
 
 ## Runbook Anatomy
 
@@ -539,51 +544,10 @@ step do
 end
 ```
 
-## Configuration
-
-Runbook is configured using its configuration object. Below is an example of how to configure Runbook.
-
-```ruby
-Runbook.configure do |config|
-  config.ssh_kit.umask = "077"
-  config.ssh_kit.default_runner_config = {in: :groups, limit: 5}
-  config.ssh_kit.default_env = {rails_env: :staging}
-
-  config.enable_sudo_prompt = true
-  config.use_same_sudo_password = true
-end
-```
-
-If the `ssh_kit` configuration looks familiar, that's because it's an SSHKit Configuration object. Any configuration options set on `SSHKit.config` can be set on `config.ssh_kit`.
-
-### Configuration Files
-
-Runbook loads configuration from a number of predefined files. Runbook will attempt to load configuration from the following locations on startup: `/etc/runbook.conf`, a `Runbookfile` in a parent directory from the current directory, a `.runbook.conf` file in the current user's home directory, a file specified with `--config` on the command line, any configuration specified in a runbook. Runbook will also load configuration from these files in this order of preference, respectively. That is, configuration values specified at the project level (`Runbookfile`) will override configuration values set at the global level (`/etc/runbook.conf`), etc.
-
 ## Working With Runbooks
 
 You can integrate with Runbook in several different ways. You can create your own project or incorporate Runbook into your existing projects. You can use Runbook via the command line. And you can even create self-executing runbooks.
 
-### From Within Your Project
-
-Runbooks can be executed using the `Runbook::Viewer` and `Runbook::Runner` classes.
-
-#### Executing a runbook using `Runbook::Viewer`
-
-```ruby
-Runbook::Viewer.new(book).generate(view: :markdown)
-```
-
-In this case book is a `Runbook::Entities::Book` and `:markdown` refers to the specific view type (`Runbook::Views::Markdown`).
-
-#### Executing a runbook using `Runbook::Runner`
-
-```ruby
-Runbook::Runner.new(book).run(run: :ssh_kit, noop: false, auto: false, paranoid: true, start_at: "0")
-```
-
-This will execute `book` using the `Runbook::Runs::SSHKit` run type. It will not run the book in `noop` mode. It will not run the book in `auto` mode. It will run the book in `paranoid` mode. And it will start at the beginning of the book. Noop mode runs the book without side-effects outside of printing what it will execute. Auto mode will skip any prompts in the runbook. If there are any required prompts in the runbook (such as the `ask` statement), then the run will fail. Paranoid mode will prompt the user for whether they should continue at every step. Finally `start_at` can be used to skip parts of the runbook or to restart at a certain point in the event of failures, stopping and starting the runbook, etc.
-
 ### Via The Command Line
 
 Runbook can be used to write stand-alone runbook files that can be executed via the command line. Below is a list of examples of how to use Runbook via the command line.
@@ -637,6 +601,26 @@ the runbook at runtime.
 $ HOSTS="appbox{01..30}.prod" ENV="production" runbook exec --start-at 1.2.1 my_runbook.rb
 ```
 
+### From Within Your Project
+
+Runbooks can be executed using the `Runbook::Viewer` and `Runbook::Runner` classes. Using these classes, you can invoke runbooks from within your existing codebase. This could be ideal for several reasons. It allows you to maintain a consistent interface with other system tasks such as rake tasks or cap tasks. It allows you to perform setup or sanity check functionality before executing your runbooks. And it allows you to load an environment to be accessed within your runbooks, such as providing access to a canonical list of servers or shared business logic.
+
+#### Executing a runbook using `Runbook::Viewer`
+
+```ruby
+Runbook::Viewer.new(book).generate(view: :markdown)
+```
+
+In this case book is a `Runbook::Entities::Book` and `:markdown` refers to the specific view type (`Runbook::Views::Markdown`).
+
+#### Executing a runbook using `Runbook::Runner`
+
+```ruby
+Runbook::Runner.new(book).run(run: :ssh_kit, noop: false, auto: false, paranoid: true, start_at: "0")
+```
+
+This will execute `book` using the `Runbook::Runs::SSHKit` run type. It will not run the book in `noop` mode. It will not run the book in `auto` mode. It will run the book in `paranoid` mode. And it will start at the beginning of the book. Noop mode runs the book without side-effects outside of printing what it will execute. Auto mode will skip any prompts in the runbook. If there are any required prompts in the runbook (such as the `ask` statement), then the run will fail. Paranoid mode will prompt the user for whether they should continue at every step. Finally `start_at` can be used to skip parts of the runbook or to restart at a certain point in the event of failures, stopping and starting the runbook, etc.
+
 ### Self-executable
 
 Runbooks can be written to be self-executable
@@ -673,6 +657,27 @@ runbook = Runbook.books.last # Runbooks register themselves to Runbook.books whe
 Runbook::Runner.new(runbook).run(auto: true)
 ```
 
+## Configuration
+
+Runbook is configured using its configuration object. Below is an example of how to configure Runbook.
+
+```ruby
+Runbook.configure do |config|
+  config.ssh_kit.umask = "077"
+  config.ssh_kit.default_runner_config = {in: :groups, limit: 5}
+  config.ssh_kit.default_env = {rails_env: :staging}
+
+  config.enable_sudo_prompt = true
+  config.use_same_sudo_password = true
+end
+```
+
+If the `ssh_kit` configuration looks familiar, that's because it's an SSHKit Configuration object. Any configuration options set on `SSHKit.config` can be set on `config.ssh_kit`.
+
+### Configuration Files
+
+Runbook loads configuration from a number of predefined files. Runbook will attempt to load configuration from the following locations on startup: `/etc/runbook.conf`, a `Runbookfile` in a parent directory from the current directory, a `.runbook.conf` file in the current user's home directory, a file specified with `--config` on the command line, any configuration specified in a runbook. Runbook will also load configuration from these files in this order of preference, respectively. That is, configuration values specified at the project level (`Runbookfile`) will override configuration values set at the global level (`/etc/runbook.conf`), etc.
+
 ## Best Practices
 
 The following are best practices when developing your own runbooks.
@@ -695,12 +700,60 @@ rails_env = `facter rails_env`
 customer_list = File.read("/tmp/customer_list.txt")
 ```
 
+### Passing State
+
+Runbook provides a number of different mechanisms for passing state throughout a runbook. For any data that is known at compile time, local variables can be used because Runbooks are lexically scoped.
+
+```ruby
+home_planet = "Krypton"
+Runbook.book "Book Using Local Variables" do
+  hometown = "Smallville"
+
+  section "My Biography" do
+    step do
+      note "Home Planet: #{home_planet}"
+      note "Home Town: #{hometown}"
+    end
+  end
+end
+```
+
+When looking to pass data generated at runtime, for example data from `ruby_command`, `ask`, or `capture` statements, Runbook persists and synchronizes instance variables for these commands.
+
+```ruby
+Runbook.book "Book Using Instance Variables" do
+  section "The Transported Man" do
+    step do
+      ask "Who's the greatest magician?", into: :greatest, default: "Alfred Borden"
+      ruby_command { @magician = "Robert Angier" }
+    end
+
+    step do
+      ruby_command {
+        note "Magician: #{@magician}"
+        note "Greatest Magician: #{@greatest}"
+      }
+    end
+  end
+end
+```
+
+Instance variables are only passed between statements such as `ruby_command`. They should not be set on entities such as steps, sections, or books. Instance variables are persisted using `metadata[:repo]`. They are copied to the repo after each statement finishes executing and copied from the repo before each statement starts executing. Because instance variables utilize the repo, they are persisted if the runbook is stopped and restarted at the same step.
+
+Be careful with your naming of instance variables as it is possible to clobber the step's DSL methods because they share the same namespace.
+
 ### Execution Best Practices
 
 As a best practice, Runbooks should always be nooped before they are run. This will allow you to catch runtime errors such as using the ask statement when running in auto mode, typos in your runbooks, and to visually confirm what will be executed.
 
 Additionally, it can be nice to have a generated view of the runbook you are executing to have a good high-level overview of the steps in the runbook.
 
+### Remote Command Execution
+
+Runbook uses [SSHKit](https://github.com/capistrano/sshkit) for remote command execution. When specifying `servers`, you are specifying the target host to execute the command. If you want to use a non-standard port or login using a different user than your current user, then you can specify the `server` as `lucy@host1.prod:2345`. Alternatively, you can use an ssh config file such as `~/.ssh/config` to specify the user and port used to ssh to a given host. See [Capistrano's SSH setup instructions](https://capistranorb.com/documentation/getting-started/installation/#ssh) for further support on setting up SSH to execute commands on remote hosts.
+
+The `user` setter designates the user you will sudo as once sshed to the remote host. Runbook supports password-protected sudo execution. That is, if your server requires a password to execute commands as another user, Runbook will allow you to enter your password when prompted. The `enable_sudo_prompt` configuration value controls this behavior. Enabling the sudo password prompt requires that your commands execute using a tty, which can lead to unexpected behavior when executing certain commands. Enabling `use_same_sudo_password` will use the same password accross different hosts and users instead of re-prompting for each unique user/host combo.
+
 ### Composing Runbooks
 
 Runbooks can be composed using the `add` keyword. Below is an example of composing a runbook from smaller, reusable components.
@@ -720,6 +773,8 @@ Runbook.book "Update configuration" do
 end
 ```
 
+If you want to parameterize these runbook snippets, you can place them in a ruby function that takes arguments and generates the desired entity or statement. If these snippets set information that is used by the runbook, such as with `capture` statements, it is a good practice to parameterize where the result is stored. This lets the snippet fit different contexts and makes clear what data is being returned from the snippet.
+
 ### Deep Nesting
 
 Because the Runbook DSL is declarative, it is generally discouraged to develop elaborate nested decision trees. For example, it is discouraged to use the `ask` statement to gather user feedback, branch on this information in a `ruby_command`, and follow completely separate sets of steps. This is because deep nesting eliminates the benefits of the declarative DSL. You can no longer noop the deeply nested structure for example.
@@ -759,48 +814,6 @@ runbook = eval(File.read("my_runbook.rb"))
 
 Loading your runbook file is more ideal, but adds slight complexity. This method is prefered because the Ruby mechanism for retrieving source code does not work for code that has been `eval`ed. This means that you will not see `ruby_command` code blocks in view and noop output when using the `eval` method. You will see an "Unable to retrieve source code" message instead.
 
-### Passing State
-
-Runbook provides a number of different mechanisms for passing state throughout a runbook. For any data that is known at compile time, local variables can be used because Runbooks are lexically scoped.
-
-```ruby
-home_planet = "Krypton"
-Runbook.book "Book Using Local Variables" do
-  hometown = "Smallville"
-
-  section "My Biography" do
-    step do
-      note "Home Planet: #{home_planet}"
-      note "Home Town: #{hometown}"
-    end
-  end
-end
-```
-
-When looking to pass data generated at runtime, for example data from `ruby_command`, `ask`, or `capture` statements, Runbook persists and synchronizes instance variables for these commands.
-
-```ruby
-Runbook.book "Book Using Instance Variables" do
-  section "The Transported Man" do
-    step do
-      ask "Who's the greatest magician?", into: :greatest, default: "Alfred Borden"
-      ruby_command { @magician = "Robert Angier" }
-    end
-
-    step do
-      ruby_command {
-        note "Magician: #{@magician}"
-        note "Greatest Magician: #{@greatest}"
-      }
-    end
-  end
-end
-```
-
-Instance variables are only passed between statements such as `ruby_command`. They should not be set on entities such as steps, sections, or books. Instance variables are persisted using `metadata[:repo]`. They are copied to the repo after each statement finishes executing and copied from the repo before each statement starts executing. Because instance variables utilize the repo, they are persisted if the runbook is stopped and restarted at the same step.
-
-Be careful with your naming of instance variables as it is possible to clobber the step's DSL methods because they share the same namespace.
-
 ## Generators
 
 Runbook provides a number of generators accessible via the command line that can be used to generate code for new runbooks, Runbook projects, and Runbook extensions. Additionally, Runbook provides a generator generator so you can define your own custom generators.
@@ -849,28 +862,47 @@ Generate your own generator using the `generate generator` command
 
 Runbook can be extended to add custom functionality.
 
-### Adding Runs and Views
+### Adding New Statements
 
-You can add new run and view types by defining modules under `Runbook:::Runs` and `Runbook::Views` respectively. They will automatically be accessible from the command line or via the `Runner` and `Viewer` classes. See `lib/runbook/runs/ssh_kit.rb` or `lib/runbook/views/markdown.rb` for examples of how to implement runs and views.
+In order to add a new statement to your DSL, create a class under `Runbook::Statements` that inherits from `Runbook::Statement`. This statement will be initialized with all arguments passed to the corresponding keyword in the DSL. Remember to also add a corresponding method to runs and views so your new statement can be interpretted in each context.
 
 ```ruby
-module Runbook::Views
-  module Yaml
-    include Runbook::View
+module Runbook::Statements
+  class Diagram < Runbook::Statement
+    attr_reader :alt_text, :url
 
-    # handler names correspond to the entity or statement class name
-    # Everything is underscored and "::" is replaced by "__"
-    def self.runbook__entities__book(object, output, metadata)
-      output << "---\n"
-      output << "book:\n"
-      output << "  title: #{object.title}\n"
+    def initialize(alt_text, url)
+      @alt_text = alt_text
+      @url = url
     end
+  end
+end
+```
 
-    # Add other handlers here
+In the above example a keyword `diagram` will be added to the step dsl and its arguments will be used to initialize the Diagram object.
+
+New statements can be generated using the statement generator.
+
+    $ runbook generate statement diagram --root lib/runbook/extensions
+
+### Adding Run and View Functionality
+
+You can add handlers for new statements and entities to your runs and views by prepending the modules with the new desired functionality.
+
+```ruby
+module MyRunbook::Extensions
+  module Diagram
+    def self.runbook__entities__diagram(object, output, metadata)
+      output << "![#{object.alt_text}](#{object.url})"
+    end
   end
+
+  Runbook::Views::Markdown.prepend(Diagram)
 end
 ```
 
+If you are not modifying existing methods, you can simply re-open the module to add new methods.
+
 ### DSL Extensions
 
 You can add arbitrary keywords to your entity DSLs. For example, you could add an alias to Runbook's Book DSL as follows:
@@ -889,43 +921,32 @@ module MyRunbook::Extensions
 end
 ```
 
-### Adding New Statements
-
-In order to add a new statement to your DSL, create a class under `Runbook::Statements` that inherits from `Runbook::Statement`. This statement will be initialized with all arguments passed to the corresponding keyword in the DSL. Remember to also add a corresponding method to runs and views so your new statement can be interpretted in each context.
-
-```ruby
-module Runbook::Statements
-  class Diagram < Runbook::Statement
-    attr_reader :alt_text, :url
-
-    def initialize(alt_text, url)
-      @alt_text = alt_text
-      @url = url
-    end
-  end
-end
-```
+DSL extensions can be generated using the dsl_extension generator.
 
-In the above example a keyword `diagram` will be added to the step dsl and its arguments will be used to initialize the Diagram object.
+    $ runbook generate dsl_extension aliases --root lib/runbook/extensions
 
-### Adding Run and View Functionality
+### Adding Runs and Views
 
-You can add handlers for new statements and entities to your runs and views by prepending the modules with the new desired functionality.
+You can add new run and view types by defining modules under `Runbook:::Runs` and `Runbook::Views` respectively. They will automatically be accessible from the command line or via the `Runner` and `Viewer` classes. See `lib/runbook/runs/ssh_kit.rb` or `lib/runbook/views/markdown.rb` for examples of how to implement runs and views.
 
 ```ruby
-module MyRunbook::Extensions
-  module Diagram
-    def self.runbook__entities__diagram(object, output, metadata)
-      output << "![#{object.alt_text}](#{object.url})"
+module Runbook::Views
+  module Yaml
+    include Runbook::View
+
+    # handler names correspond to the entity or statement class name
+    # Everything is underscored and "::" is replaced by "__"
+    def self.runbook__entities__book(object, output, metadata)
+      output << "---\n"
+      output << "book:\n"
+      output << "  title: #{object.title}\n"
     end
-  end
 
-  Runbook::Views::Markdown.prepend(Diagram)
+    # Add other handlers here
+  end
 end
 ```
 
-If you are not modifying existing methods, you can simply re-open the module to add new methods.
-
 ### Augmenting Functionality With Hooks
 
 You can add `before`, `after`, or `around` hooks to any statement or entity by defining a hook on a `Run` or `View`.
@@ -1024,7 +1045,20 @@ module MyRunbook::Extensions
 end
 ```
 
-This will add a `log_level` attribute to Runbook's configuration with a default value of `:info`.
+This will add a `log_level` attribute to Runbook's configuration with a default value of `:info`. This configuration value can be accessed via `Runbook.config.log_level`.
+
+## Testing
+
+Runbooks are inherently difficult to test because they are primarily composed of side-effects. That being said, there are a number of strategies you can employ to test your runbooks.
+
+1. Push complex logic to stand-alone Ruby objects that can be tested in isolation
+2. Use `TEST` or `DEBUG` environment variables to conditionally disable side-effects during execution
+3. Execute your runbooks in staging environments
+4. Noop your runbooks to understand what they will be executing before executing them
+
+See Runbook's test suite for more ideas on how to test your runbooks. For example, Runbook uses [aruba](https://github.com/cucumber/aruba) to test Runbook at the CLI level.
+
+Additionally, runbooks should contain their own assertions, sanity checks, monitoring, and alerting to mitigate errors and alert you if intervention is required.
 
 ## Known Issues
 
@@ -1094,7 +1128,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/braint
 
 ## Feature Requests
 
-Any feature requests are always welcome and will be considered in accordance with time and need. Additionally, existing feature requests are tracked in TODO.md. If you choose to contribute, your contributions will be greatly appreciated.
+Any feature requests are always welcome and will be considered in accordance with time and need. Additionally, existing feature requests are tracked in TODO.md. If you choose to contribute, your contributions will be greatly appreciated. Please reach out before creating any substantial pull requests. A bit of discussion can save a lot of time and increase the chances that your pull request will be accepted.
 
 ## License
 

data/bin/console

@@ -6,6 +6,8 @@ require "runbook"
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
+Runbook::Configuration.load_config
+
 # (If you use this, don't forget to add pry to your Gemfile!)
 require "pry"
 Pry.start

data/lib/runbook/cli.rb

@@ -1,7 +1,7 @@
 require "thor"
 require "runbook"
 require "runbook/cli_base"
-require "runbook/installer"
+require "runbook/initializer"
 
 # Needed to load custom generators
 Runbook::Configuration.load_config
@@ -71,15 +71,26 @@ module Runbook
     LONGDESC
     subcommand "generate", Runbook::Generator
 
-    desc "install", "Install Runbook into an existing project"
+    desc "init", "Initialize Runbook in an existing project"
     long_desc "Set up Runbook directory structure and Runbookfile in an existing project for executing runbooks."
-    Runbook::Installer.class_options.values.each do |co|
+    Runbook::Initializer.class_options.values.each do |co|
+      method_option co.name, desc: co.description, required: co.required,
+        default: co.default, aliases: co.aliases, type: co.type,
+        banner: co.banner, hide: co.hide
+    end
+    def init
+      invoke(Runbook::Initializer)
+    end
+
+    desc "install", "Install Runbook in an existing project", hide: true
+    Runbook::Initializer.class_options.values.each do |co|
       method_option co.name, desc: co.description, required: co.required,
         default: co.default, aliases: co.aliases, type: co.type,
         banner: co.banner, hide: co.hide
     end
     def install
-      invoke(Runbook::Installer)
+      Runbook.deprecator.deprecation_warning(:install, :init)
+      invoke(Runbook::Initializer)
     end
 
     desc "--version", "Print runbook's version"

data/lib/runbook/configuration.rb

@@ -1,6 +1,10 @@
 module Runbook
   class << self
     attr_accessor :configuration
+
+    def config
+      @configuration
+    end
   end
 
   def self.configure

data/lib/runbook/{installer.rb → initializer.rb}

@@ -1,5 +1,5 @@
 module Runbook
-  class Installer < Thor::Group
+  class Initializer < Thor::Group
     include Thor::Actions
 
     source_root File.join(
@@ -59,10 +59,10 @@ module Runbook
       _keep_dir(target)
     end
 
-    def runbook_installation_overview
+    def runbook_initialization_overview
       msg = [
         "",
-        "Runbook was successfully installed",
+        "Runbook was successfully initialized.",
         "Add runbooks to the `runbooks` directory.",
         "Add shared code to `lib/runbook`.",
         "Execute runbooks using `bundle exec runbook exec <RUNBOOK_PATH>`",

data/lib/runbook/run.rb

@@ -42,7 +42,8 @@ module Runbook
         toolbox.output("Step #{metadata[:position]}:#{title}\n\n")
         return if metadata[:auto] || metadata[:noop] ||
           !metadata[:paranoid] || object.title.nil?
-        continue_result = toolbox.expand("Continue?", _step_choices)
+        step_choices = _step_choices(object, metadata)
+        continue_result = toolbox.expand("Continue?", step_choices)
         _handle_continue_result(continue_result, object, metadata)
       end
 
@@ -210,7 +211,7 @@ module Runbook
         object.class.to_s.underscore.gsub("/", "__")
       end
 
-      def _step_choices
+      def _step_choices(object, metadata)
         [
           {key: "c", name: "Continue to execute this step", value: :continue},
           {key: "s", name: "Skip this step", value: :skip},

data/lib/runbook/util/runbook.rb

@@ -15,6 +15,16 @@ module Runbook
     _child_classes(Runbook::Generators)
   end
 
+  def self.deprecator
+    return @deprecator if @deprecator
+    major_version = Gem::Version.new(Runbook::VERSION).segments[0]
+    next_major_version = major_version + 1
+    @deprecator = ActiveSupport::Deprecation.new(
+      "#{next_major_version}.0",
+      "Runbook"
+    )
+  end
+
   def self._child_classes(mod)
     mod.constants.map { |const|
       "#{mod.to_s}::#{const}".constantize

data/lib/runbook/version.rb

@@ -1,3 +1,3 @@
 module Runbook
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

data/runbook.gemspec

@@ -32,17 +32,17 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency 'activesupport', '~> 5.0', '>= 5.0.0.1'
-  spec.add_runtime_dependency "method_source", "~> 0.9.0"
+  spec.add_runtime_dependency "method_source", "~> 0.9"
   spec.add_runtime_dependency "sshkit", "1.16"
-  spec.add_runtime_dependency "sshkit-sudo", "~> 0.1.0"
+  spec.add_runtime_dependency "sshkit-sudo", "~> 0.1"
   spec.add_runtime_dependency "airbrussh", "~> 1.3"
-  spec.add_runtime_dependency "thor", "~> 0.20.0"
-  spec.add_runtime_dependency "tty-progressbar", "~> 0.14.0"
-  spec.add_runtime_dependency "tty-prompt", "~> 0.16.0"
+  spec.add_runtime_dependency "thor", "~> 0.20"
+  spec.add_runtime_dependency "tty-progressbar", "~> 0.14"
+  spec.add_runtime_dependency "tty-prompt", "~> 0.16"
 
-  spec.add_development_dependency "aruba", "~> 0.14.5"
+  spec.add_development_dependency "aruba", "~> 0.14"
   spec.add_development_dependency "bundler", "~> 1.15"
-  spec.add_development_dependency "pry", "~> 0.11.3"
+  spec.add_development_dependency "pry", "~> 0.11"
   spec.add_development_dependency "pry-byebug", "~> 3.6"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runbook
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - pblesi
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-10 00:00:00.000000000 Z
+date: 2019-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: sshkit
   requirement: !ruby/object:Gem::Requirement
@@ -64,14 +64,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: airbrussh
   requirement: !ruby/object:Gem::Requirement
@@ -92,56 +92,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: tty-progressbar
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: tty-prompt
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: '0.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: '0.16'
 - !ruby/object:Gem::Dependency
   name: aruba
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.5
+        version: '0.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.5
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -162,14 +162,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.3
+        version: '0.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.3
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -278,7 +278,7 @@ files:
 - lib/runbook/helpers/ssh_kit_helper.rb
 - lib/runbook/helpers/tmux_helper.rb
 - lib/runbook/hooks.rb
-- lib/runbook/installer.rb
+- lib/runbook/initializer.rb
 - lib/runbook/node.rb
 - lib/runbook/run.rb
 - lib/runbook/runner.rb