runbook 0.14.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cb2a40c659a212a9fda6d78d1e94b07ba51625896cd6e4f4a4b6668e42bbc4e
-  data.tar.gz: 065708ff0b3bd93dfdcc35b60730138053e64af9e78768176282f5dc59236b66
+  metadata.gz: 11c80dcba3596671291c8d9dbd40a33ae5691963b27dffdd7459cb4f4ebd94be
+  data.tar.gz: a8a578797429344e1fa29c84cb395db5c9c725f4b35b00440e26708328fdca26
 SHA512:
-  metadata.gz: 87559cf0bee8e17052a2639033a96481fba11963e50c596f138e64fc72b54328288202bfbe3576da6417eada36f219123ba54d726ab0cc6b28176f31552d21ae
-  data.tar.gz: a0b414a4f0b8fa499cc46362d03d2dfb814cf65a46decbd796ffc45e7ecbd0f68db7a2a89168a3ace032814893ef649fa3a1d36982315f548688f4ce7e470b3c
+  metadata.gz: bda3ee51331bcac0c38f338e4ddcf001847328f07093ff1163b8a8b4394e523b116c05b88de449d7072dc90fbe51da3049f00778933a8e8d0b8d3eac39c935c0
+  data.tar.gz: 11420133d97afa081df1105bbf3dc1364b5722aa50e57f49777f761c2df88b152b50b4db80c2da81a8d10328bc85b46de51721a010113d26b965411243a51e68

data/.dockerignore

@@ -0,0 +1,17 @@
+**/.git
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# recommended:
+# https://github.com/thoughtbot/appraisal#version-control
+gemfiles/*.gemfile.lock

data/.gitignore

@@ -10,3 +10,7 @@
 
 # rspec failure tracking
 .rspec_status
+
+# recommended:
+# https://github.com/thoughtbot/appraisal#version-control
+gemfiles/*.gemfile.lock

data/.ruby-version

@@ -1 +1 @@
-ruby-2.2.3
+ruby-2.5.5

data/.travis.yml

@@ -1,9 +1,25 @@
-sudo: false
+dist: xenial
 language: ruby
+services:
+  - docker
 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
+  - 2.3.8
+  - 2.4.10
+  - 2.5.8
+  - 2.6.6
+  - 2.7.2
+  - 3.0.0
+gemfile:
+  - gemfiles/activesupport_5.gemfile
+  - gemfiles/activesupport_6.gemfile
+matrix:
+  exclude:
+    - rvm: 2.3.8
+      gemfile: gemfiles/activesupport_6.gemfile
+    - rvm: 2.4.10
+      gemfile: gemfiles/activesupport_6.gemfile
+
+before_install: gem install bundler -v 2.2.16
+
+script:
+  - bundle exec rake spec_all

data/Appraisals

@@ -0,0 +1,8 @@
+appraise "activesupport-5" do
+  gem "activesupport", "~> 5.0"
+end
+
+appraise "activesupport-6" do
+  gem "activesupport", "~> 6.0"
+end
+

data/CHANGELOG.md

@@ -4,6 +4,77 @@ This log maintains a list of all substantive changes to Runbook. The log include
 
 ## master
 
+## `v1.1.0` (2021-05-21)
+
+### Breaking Changes:
+
+* Removes `runbook install` (should have happened in v1.0.0)
+* Drops support for Ruby 2.2 and bundler < 2.2
+
+### Features:
+
+* Add support for Ruby 3.0.0 (thanks @pblesi!)
+* Add metadata argument that saves TMUX panes: keep_panes (thanks @ClashTheBunny)
+
+### Documentation:
+
+* Update assert parameters description
+* Update example for module class method (thanks @voodoologic!)
+
+## `v1.0.0` (2020-07-24)
+
+### Breaking Changes:
+
+* Commands and tmux commands that previously escaped single quotes will now require un-escaped single quotes
+
+### Features:
+
+* Add Node#parent_entity to find the containinng entity for a node
+
+### Fixes:
+
+* Fix bugs requiring escaping single quotes in commands and tmux_commands (BACKWARDS INCOMPATIBLE CHANGE)
+* Fix `File.exists?` deprecation warning (Thanks onk!)
+
+### Documentation:
+
+* Add suppress_capture_output.rb runbook example
+
+## `v0.16.1` (2019-11-25)
+
+### Fixes:
+
+* Fix bug preventing skipping of steps not nested in sections (Thanks celeen!)
+
+## `v0.16.0` (2019-11-22)
+
+### Fixes:
+
+* Add better error messages for runtime values accessed at compile time
+
+### New Features
+
+* Add entity tags and labels
+* Add `setup` entity for initial runbook setup code
+* Add `Runbook.views` method for accessing an array of all defined views
+* Add airbrussh context for better ssh_kit output
+* Backtick "into" targets in markdown view output (Thanks fwolfst!)
+
+## `v0.15.0` (2019-09-29)
+
+### Fixes:
+
+* Halt the project generator if gem generation fails
+* Replace timeout_statement with abort_statement for assert statements
+* Make runbook state files only readable by the current user
+* Allow / characters in the title of a runbook (Thanks brafales!)
+
+### New Features
+
+* Allow books to have steps as children
+* Allow "echo: false" for ask statements
+* Expose "run" as an argument to ruby_commands
+
 ## `v0.14.0` (2019-08-15)
 
 ### Fixes:

data/README.md

@@ -2,6 +2,7 @@
 
 [![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)
+[![Gitter](https://badges.gitter.im/braintree/runbook.svg)](https://gitter.im/braintree/runbook?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 _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._
 
@@ -118,10 +119,12 @@ Initialize Runbook in your project:
 
 * [1. Runbook Anatomy](#runbook-anatomy)
   * [1.1 Entities, Statements, and Setters](#entities-statements-and-setters)
-    * [1.1.1 Books, Sections, and Steps](#books-sections-and-steps)
+    * [1.1.1 Books, Sections, Steps, and Setup](#books-sections-steps-and-setup)
       * [1.1.1.1 Books](#books)
       * [1.1.1.2 Sections](#sections)
       * [1.1.1.3 Steps](#steps)
+      * [1.1.1.4 Setup](#setup)
+      * [1.1.1.5 Tags and Labels](#tags-and-labels)
     * [1.1.2 Statements](#statements)
       * [1.1.2.1 Ask](#ask)
       * [1.1.2.2 Assert](#assert)
@@ -169,11 +172,12 @@ Initialize Runbook in your project:
   * [6.8 Adding to Runbook's Configuration](#adding-to-runbooks-configuration)
 * [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)
+* [9. FAQ](#faq)
+* [10. Development](#development)
+* [11. Contributing](#contributing)
+* [12. Feature Requests](#feature-requests)
+* [13. License](#license)
+* [14. Code of Conduct](#code-of-conduct)
 
 ## Runbook Anatomy
 
@@ -220,7 +224,7 @@ Hierarchically, a runbook looks like this:
 
 A runbook is composed of entities, statements, and setters. Runbook entities contain either other entities or statements. Examples of entities include Books, Sections, and Steps. They define the structure of the runbook and can be considered the "nodes" of the tree structure. As entities are the nodes of the tree structure, statements are the "leaves" of the structure and comprise the various behaviors or commands of the runbook. Setters, typically referenced from within steps, associate state with the node, which can be accessed by its children.
 
-#### Books, Sections, and Steps
+#### Books, Sections, Steps, and Setup
 
 Entities are composed of a title and a list of items which are their children. Each entity can be rendered with a specific view or executed with a specific run.
 
@@ -233,7 +237,7 @@ Runbook.book "Unbalance node" do
 end
 ```
 
-Every book requires a title. Books can have description, layout, and section children. Descriptions describe the book and are declared with the `description` keyword.
+Every book requires a title. Books can have description, layout, section, and step children. Descriptions describe the book and are declared with the `description` keyword.
 
 ##### Sections
 
@@ -243,31 +247,91 @@ A book is broken up into sections. Every section requires a title. Sections can
 
 Steps hold state and group together a set of statements. Steps do not require titles or children. This allows runbooks to be very flexible. You can fill out steps as needed, or be terse when the behavior of the step is self-evident. Steps without titles will not prompt to continue when running in paranoid mode.
 
+##### Setup
+
+Setup is a special entity that is always executed. It is not skipped when starting or resuming execution in the middle of a runbook. A prompt is never presented to determine if you should or should not execute the setup section. The setup section is similar to the step entity in that it shares the same DSL. In other words, any keywords available within steps are also available within the setup section.
+
+The setup section provides two important use cases. First, it allows you ensure any dependent values are defined when executing your runbook. If skipping the initial steps of your runbook and starting in the middle, you can be sure that any initialization steps have been executed. For example, presume you have a runbook that prompts for a list of servers, stops the servers, and then starts them. It would be advantageous to define the prompting server logic in a setup section, so you can start the runbook at the start server step and know that the list of servers is defined.
+
+Second, if you dynamically define the sections and steps in your runbook based on user input, then doing this in the setup section allows you start the runbook in the middle of the dynamically defined steps.
+
+Because the setup section is always executed, it's execution should be idempotent. In other words, the setup section should be able to be executed multiple times in a row and produce the same result.
+
+It may be ideal to ensure user input is only asked for once when executing a setup section.
+
+```ruby
+Runbook.book "Make Pizza" do
+  setup do
+    ruby_command do
+      @toppings ||= ENV["TOPPINGS"]
+      ask "What toppings would you like?", into: :toppings, default: "cheese" unless @toppings
+    end
+  end
+end
+```
+
+The above example will set `@toppings` from a passed-in environment variable if present, otherwise it will ask the user to set `@toppings`. If toppings have already has been defined from a previous execution, it will not prompt the user for the value again. Because this logic references a value that is defined at runtime (`@toppings`), it must be wrapped in a `ruby_command`.
+
+##### Tags and Labels
+
+Any entity can be associated with arbitrary tags or labels. Once tags or labels are assigned, entity behavior can be modified using [hooks](#augmenting-functionality-with-hooks).
+
+```ruby
+Runbook.book "Bounce Nodes", :untested do
+  step "Disable monitoring", :skip do
+    confirm "Have you disabled health monitoring?"
+  end
+
+  step "Restart nodes", :aws_only, :mutator, labels: {rails_env: :production} do
+    confirm "Have you restarted the nodes?"
+  end
+end
+```
+
+```ruby
+Runbook::Runs::SSHKit.register_hook(:warn_for_untested_runbook, :before, Runbook::Entities::Book) do |object, metadata|
+  warning = "This runbook has not yet been tested. Beware of bugs!"
+  metadata[:toolbox].warn(warning) if object.tags.include?(:untested)
+end
+
+Runbook::Runs::SSHKit.register_hook(:skip_skippable_entities, :around, Runbook::Entity) do |object, metadata, block|
+  next if object.tags.include?(:skip)
+  next if object.labels[:rails_env] && object.labels[:rails_env] != ENV["RAILS_ENV"]
+  block.call
+end
+```
+
 #### Statements
 
 Statements are the workhorses of runbooks. They comprise all the behavior runbooks execute. Runbook comes with the following statements:
 
 ##### Ask
 
-Prompts the user for a string and stores its value on the containing step entity. Once this statement is executed, its value is accessed as an instance variable under the `into` parameter. This value can be referenced in later statements such as the `ruby_command` statement.
+Prompts the user for a string and stores its value on the containing step entity. Once this statement is executed, its value is accessed as an instance variable under the `into` parameter. This value can be referenced in later statements such as the `ruby_command` statement. An optional `default` value can be specified. An optional `echo` parameter can be specified to indicate whether typed input should be echoed to the screen.
 
 ```ruby
-ask "What percentage of requests are failing?", into: :failing_request_percentage, default: "100"
+ask "What percentage of requests are failing?", into: :failing_request_percentage, default: "100", echo: true
+
+ruby_command do
+  note "Failing request percentage: #{@failing_request_percentage}"
+end
 ```
 
+In the above example, the `note` statement must be wrapped in a `ruby_command` statement. Without wrapping `note` in a `ruby_command`, it would be evaluated at compile time but the user will only be asked for input when the runbook is executed (so `@failing_request_percentage` would not have a value). If you find yourself wrapping many or all runbook statements in ruby commands it may make sense to set these values at compile time using environment variables.
+
 ##### Assert
 
-Runs the provided `cmd` repeatedly until it returns true. A timeout and maximum number of attempts can be set. You can specify a command to be run if a timeout occurs or the maximum number of attempts is hit. Commands can optionally be specified as `raw`. This tells SSHKit to not perform auto-wrapping of the commands, but execute the exact string on the remote server. See SSHKit's documentation for more details.
+Runs the provided `cmd` repeatedly until it returns true. A timeout and maximum number of attempts can be set. When either the attempt or timeout limit is hit, a command can be specified that will be run. If no command is specified, the process will fail. Commands can optionally be specified as `raw`. This tells SSHKit to not perform auto-wrapping of the commands, but execute the exact string on the remote server. See SSHKit's documentation for more details.
 
 ```ruby
 assert(
   'service nginx status | grep "is running"',
   cmd_ssh_config: {servers: ["host1.prod"], parallelization: {strategy: :parallel}},
   cmd_raw: false,
-  interval: 3, # seconds
-  timeout: 300, # seconds
-  attempts: 3,
-  timeout_statement: Runbook::Statements::Command.new(
+  interval: 3,   # How often, in seconds, to wait between tries
+  timeout: 300,  # Total time, in seconds, to keep trying command, after which it will fail
+  attempts: 3,   # Total number of attempts after which the process will fail
+  abort_statement: Runbook::Statements::Command.new(
     "echo 'help' | mail -s 'need help' page-me@page-me.com",
     ssh_config: {servers: [:local], parallelization: {strategy: :parallel}},
     raw: false
@@ -277,7 +341,7 @@ assert(
 
 ##### Capture
 
-Runs the provided `cmd` and captures its output into `into`. An optional `ssh_config` can be specified to configure how the capture command gets run. Capture commands take an optional `strip` parameter that indicates if the returned output should have leading and trailing whitespace removed. Capture commands also take an optional `raw` parameter that tells SSHKit whether the command should be executed as is, or to include the auto-wrapping of the ssh_config.
+Runs the provided `cmd` and captures its output into `into`. Once captured, this value can be referenced in later statements such as the `ruby_command` statement. An optional `ssh_config` can be specified to configure how the capture command gets run. Capture commands take an optional `strip` parameter that indicates if the returned output should have leading and trailing whitespace removed. Capture commands also take an optional `raw` parameter that tells SSHKit whether the command should be executed as is, or to include the auto-wrapping of the ssh_config.
 
 ```ruby
 capture %Q{wc -l file.txt | cut -d " " -f 1}, into: :num_lines, strip: true, ssh_config: {user: "root"}
@@ -323,7 +387,7 @@ DESC
 Downloads the specified file to `to`. An optional `ssh_config` can be specified to configure how the download command gets run, for example specifying the remote host and remote directory to download from. Optional `options` can be specified that get passed down to the underlying sshkit implementation
 
 ```ruby
-download /home/pblesi/rad_file.txt, to: my_rad_file.txt, ssh_config: {servers: ["host1.prod"]}, options: {log_percent: 10}
+download '/home/pblesi/rad_file.txt', to: my_rad_file.txt, ssh_config: {servers: ["host1.prod"]}, options: {log_percent: 10}
 ```
 
 ##### Layout
@@ -355,10 +419,10 @@ notice "There be dragons!"
 
 ##### Ruby Command
 
-Executes its block in the context of the parent step. The block is passed the ruby_command statement and the execution metadata as arguments.
+Executes its block in the context of the parent step. The block is passed the ruby_command statement, the execution metadata, and the run as arguments.
 
 ```ruby
-ruby_command do |rb_cmd, metadata|
+ruby_command do |rb_cmd, metadata, run|
   if (failure_rate = rb_cmd.parent.failing_request_percentage) > 25
     `echo 'Help! failure rate at #{failure_rate}' | mail -s 'High failure rate!' page-me@page-me.com`
   else
@@ -379,6 +443,7 @@ Metadata at execution time is structured as follows:
   noop: false, # A boolean indicating if you are running in noop mode. ruby_command blocks are never evaluated in noop mode
   auto: false, # A boolean indicating if you are running in auto mode
   paranoid: true, # A boolean indicating if you are running in paranoid mode (prompting before each step)
+  keep_panes: false, # A boolean indicating whether panes should be kept open after completion
   start_at: 0, # A string representing the step where nodes should start being processed
   toolbox: Runbook::Toolbox.new, # A collection of methods to invoke side-effects such as printing and collecting input
   layout_panes: {}, # A map of pane names to pane ids. `layout_panes` is used by the `tmux_command` to identify which tmux pane to send the command to
@@ -789,7 +854,7 @@ step "Inspect plate" do
     when "carrots"
       add carrots_book
     when "peas"
-      system("runbook exec samples/print_peas.rb")
+      system("runbook exec examples/print_peas.rb")
     else
       metadata[:toolbox].warn("Found #{veggie}!")
     end
@@ -864,7 +929,7 @@ Runbook can be extended to add custom functionality.
 
 ### 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.
+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 interpreted in each context.
 
 ```ruby
 module Runbook::Statements
@@ -969,6 +1034,22 @@ end
 
 When registering a hook, you specify the name of the hook, the type, and the statement or entity to add the hook to. `before` and `after` hooks execute the block before and after executing the entity or statement, respectively. `around` hooks take a block which executes the specified entity or statement. When specifying the class that the hook applies to, you can have the hook apply to all entities by specifying `Runbook::Entity`, all statements by specifying `Runbook::Statement`, or all items by specifying `Object`. Additionally, you can specify any specific entity or statement you would like the hook to apply to.
 
+Hooks are defined on the run or view objects themselves. For example, you would register a hook with `Runbook::Runs::SSHKit` to have the hook be applied to the `SSHKit` run. You would register a hook with the `Runbook::Views::Markdown` view to have hooks apply to this view. If you want to apply a hook to all runs or views, you can use the `Runbook.runs` method or `Runbook.views` method to iterate through the runs or views respectively.
+
+```ruby
+Runbook.runs.each do |run|
+  run.register_hook(
+    :give_words_of_encouragement,
+    :before,
+    Runbook::Entities::Book
+  ) do |object, metadata|
+    metadata[:toolbox].output("You've got this!")
+  end
+end
+```
+
+Hooks can be defined anywhere prior to runbook execution. If defining a hook for only a single runbook, it makes sense to define the hook immediately prior to the runbook definition. If you want a hook to apply to all runbooks in your project, it can be defined in a config file such as the `Runbookfile`. If you want to selectively apply the hook to certain runbooks, it may make sense to define it in a file that can be required by runbooks when it is needed.
+
 When starting at a certain position in the runbook, hooks for any preceding sections and steps will be skipped. After hooks will be run for a parent when starting at a child entity of a parent.
 
 ### Adding New Run Behaviors
@@ -1062,7 +1143,7 @@ Additionally, runbooks should contain their own assertions, sanity checks, monit
 
 ## Known Issues
 
-### Command Quoting
+### Command Quoting (Prior to v1.0)
 
 Because ssh_config declarations such as `user`, `group`, `path`, `env`, and `umask` are implemented as wrappers around your provided commands, you must be aware that issues can arise if your commands contain characters such as single quotes that are not properly escaped.
 
@@ -1080,6 +1161,8 @@ command "echo '\\''I love cheese'\\''"
 
 Alternatively, if you wish to avoid issues with SSHKit command wrapping, you can specify that your commands be executed in raw form, passed directly as written to the specified host.
 
+`tmux_command` wraps the input passed to it in single quotes. Therefore any single quotes passed to the `tmux_command` should be escaped using `'\\''`. This issue can manifest itself as part of the command not being echoed to the tmux pane.
+
 ### Specifying env values
 
 When specifying the `env` for running commands, if you place curly braces `{}` around the env values, it is required to enclose the arguments in parenthesis `()`, otherwise the following syntax error will result:
@@ -1106,21 +1189,72 @@ not as
 env {rails_env: :production}
 ```
 
+## FAQ
+
+### Are runbooks compiled?
+
+Yes they are. When you define a runbook, a tree data structure is constructed much like an [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree). This is important because you do not have to worry about any side-effects such as executing server commands when this data structure is compiled. Once compiled, choosing either the run or view to execute the runbook object determines what behavior is executed at each node.
+
+### Why are runbooks compiled?
+
+Runbook is designed to minimize and mitigate issues that arise when running operations in production enviroments. One way this is accomplished is by compiling all statements in the runbook before execution is started. Validations and assertions can be made to reduce the likelihood that a runbook will encounter an error in the middle of an operation. In other words, Runbook provides some guarantees about proper formatting of a runbook before any commands execute that could affect live systems.
+
+### Why is my variable/method not set?
+
+Because runbooks are compiled, statements that set values such as `ask`, `capture`, and `capture_all` statements (using the `:into` keyword) only expose their values at runtime. This means any references to these methods or variables (specified with `:into`) can only happen within `ruby_command` blocks which are evaluated at runtime. If an argument to a statement references the values set by these statements, then the statement must be wrapped in a `ruby_command` block. See [Passing State](#passing-state) for specific examples.
+
+### How do I define and call methods within a runbook?
+
+When defining and referencing your own functions in a runbook, functions should be wrapped in a module so they can be referenced globally. For example:
+
+```ruby
+module Adder
+  def self.add(x, y)
+    x + y
+  end
+end
+
+Runbook.book "Add Two Numbers" do
+  step "Add numbers" do
+    ask "X?", into: :x
+    ask "Y?", into: :y
+
+    ruby_command do |rb_cmd, metadata, run|
+      metadata[:toolbox].output("Result: #{Adder.add(x, y)}")
+    end
+  end
+end
+```
+
+### Why does my command work on the command line but not in runbook?
+
+There are a number of reasons why a command may work directly on your command line, but not when executed using the `command` statement. Some possible things to try include:
+
+* Print the command with any variables substituted
+* Ensure the command works outside of runbook
+* Use full paths. The `PATH` environment variable may not be set.
+* Check for aliases. Aliases are usually not set for non-interactive shells.
+* Check for environment variables. Differences between your shell environment variables and those set for the executing shell may modify command behavior.
+* Check for differing behavior between the bourne shell (`sh`) and your shell (usually bash).
+* Check that quotes are properly being escaped.
+* Simplify the command you are executing and then slowly build it back up
+* Check for permissions issues that might cause different execution behavior.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
-To execute runbook using this repo, run `bundle exec exe/runbook exec samples/layout_runbook.rb`.
+To execute runbook using this repo, run `bundle exec exe/runbook exec examples/layout_runbook.rb`.
 
 To release a new version:
 
 1. Update the version number in `version.rb`.
 2. Update the changelog in `CHANGELOG.rb`.
 3. Commit changes with commit messsage: "Bump runbook version to X.Y.Z"
-4. Run `bundle exec rake release`, which will create a git tag for the version and push git commits and tags.
-5. Push the `.gem` file in `pkg` to your gem repository
+4. Run `gem signin` to ensure you can push the new version to rubygems.org
+5. Run `bundle exec rake release`, which will create a git tag for the version and push git commits and tags.
 
 ## Contributing