Update relish upgrade guide.

features/Upgrade.md

@@ -1,4 +1,75 @@
-# Upgrading from rspec-rails-1.x to rspec-rails-2.
+# Upgrading from rspec-rails-2.x to rspec-rails-3
+
+For detailed information on the RSpec 3.x upgrade process see the [RSpec Upgrade
+docs](https://relishapp.com/rspec/docs/upgrade).
+
+There is another `rspec-rails` specific change to be aware of:
+
+```text
+The default helper files created in RSpec 3.x have changed
+```
+
+In prior versions, only a single `spec_helper.rb` file was generated. This file
+has been moved to `rails_helper.rb`. The new `spec_helper.rb` is the same
+standard helper generated by running `rspec --init`.
+
+This change was made to accomplish two general goals:
+
+- Keep the installation process in sync with regular RSpec changes
+
+- Provide an out-of-the-box way to avoid loading Rails for those specs that do
+  not require it
+
+## Upgrading an Existing App
+
+For most existing apps, one of the following upgrade paths is sufficient to
+switch to the new helpers:
+
+### I need to move things over in stages
+
+1. Create a new `rails_helper.rb` with the following content:
+
+    ```ruby
+    require 'spec_helper'
+    ```
+
+2. As necessary, replace `require 'spec_helper'` with `require 'rails_helper'`
+   in the specs.
+
+3. When ready, move any Rails specific code and setup from `spec_helper.rb` to
+   `rails_helper.rb`.
+
+### I'm ready to just switch completely
+
+1. Move the existing `spec_helper.rb` to `rails_helper.rb`:
+
+    ```ruby
+    git move spec/spec_helper.rb spec/rails_helper.rb
+    ```
+
+2. Run the installation rake task opting to not replace `rails_helper.rb`:
+
+    ```console
+    $ bin/rails generate rspec:install
+          create  .rspec
+           exist  spec
+          create  spec/spec_helper.rb
+        conflict  spec/rails_helper.rb
+    Overwrite my_app/spec/rails_helper.rb? (enter "h"for help) [Ynaqdh] n
+            skip  spec/rails_helper.rb
+    ```
+
+3. Move any non-Rails RSpec configurations and customizations from your
+   `rails_helper.rb` to `spec_helper.rb`.
+
+4. Find/replace instances of `require 'spec_helper'` with
+   `require 'rails_helper'` in any specs which rely on Rails.
+
+## Generators
+
+Generators run in RSpec 3.x will use the `rails_helper` by default.
+
+# Upgrading from rspec-rails-1.x to rspec-rails-2
 
 This is a work in progress. Please submit errata, missing steps, or patches to
 the [rspec-rails issue tracker](https://github.com/rspec/rspec-rails/issues).