Properly reference rails_helper in README.

README.md

@@ -28,8 +28,13 @@ Initialize the `spec/` directory (where specs will reside) with:
 rails generate rspec:install
 ```
 
-This adds `spec/spec_helper.rb` and `.rspec` files that are used for
-configuration. See those files for more information.
+This adds the following files which are used for configuration:
+
+- `.rspec`
+- `spec/spec_helper.rb`
+- `spec/rails_helper.rb`
+
+Check the comments in each file for more information.
 
 To run your specs, use the `rspec` command:
 
@@ -53,8 +58,75 @@ be run via `bin/rspec`:
 bundle binstubs rspec-core
 ```
 
+### Upgrade note
+
+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:
+
+> 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
 
+**NOTE:** Generators run in RSpec 3.x will use the `rails_helper` by default.
+See the above [upgrade notes](#upgrade-note) about this change.
+
 Once installed, RSpec will generate spec files instead of Test::Unit test files
 when commands like `rails generate model` and `rails generate controller` are
 used.
@@ -70,7 +142,7 @@ Model specs reside in the `spec/models` folder. Use model specs to describe
 behavior of models (usually ActiveRecord-based) in the application. For example:
 
 ```ruby
-require "spec_helper"
+require "rails_helper"
 
 describe User do
   it "orders by last name" do
@@ -91,7 +163,7 @@ Controller specs reside in the `spec/controllers` folder. Use controller specs
 to describe behavior of Rails controllers. For example:
 
 ```ruby
-require "spec_helper"
+require "rails_helper"
 
 describe PostsController do
   describe "GET #index" do
@@ -138,7 +210,7 @@ intent is to specify one or more request/response cycles from end to end using
 a black box approach.
 
 ```ruby
-require 'spec_helper'
+require 'rails_helper'
 describe "home page" do
   it "displays the user's username after successful login" do
     user = User.create!(:username => "jdoe", :password => "secret")
@@ -161,7 +233,7 @@ users like to use extension libraries like
 [Capybara](https://github.com/jnicklas/capybara):
 
 ```ruby
-require 'spec_helper'
+require 'rails_helper'
 describe "home page" do
   it "displays the user's username after successful login" do
     user = FactoryGirl.create(:user, :username => "jdoe", :password => "secret")
@@ -213,7 +285,7 @@ specs](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/feature-specs/feat
 View specs live in spec/views, and mix in ActionView::TestCase::Behavior.
 
 ```ruby
-require 'spec_helper'
+require 'rails_helper'
 describe "events/index" do
   it "renders _event partial for each event" do
     assign(:events, [stub_model(Event), stub_model(Event)])
@@ -318,7 +390,7 @@ expect(rendered).to xxx
 Routing specs live in spec/routing.
 
 ```ruby
-require 'spec_helper'
+require 'rails_helper'
 describe "routing to profiles" do
   it "routes /profile/:username to profile#show for username" do
     expect(:get => "/profiles/jsmith").to route_to(
@@ -346,7 +418,7 @@ Provides a `helper` object which mixes in the helper module being spec'd, along
 with `ApplicationHelper` (if present).
 
 ```ruby
-require 'spec_helper'
+require 'rails_helper'
 describe EventsHelper do
   describe "#link_to_event" do
     it "displays the title, and formatted date" do

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).