Rails 4 schema changes docs

README.md

@@ -57,43 +57,23 @@ be run via `bin/rspec`:
 bundle binstubs rspec-core
 ```
 
-### Upgrade note
+### Upgrade Note
 
-For detailed information on the RSpec 3.x upgrade process see the
+For detailed information on the general RSpec 3.x upgrade process see the
 [RSpec Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
 
-There are two particular `rspec-rails` specific changes to be aware of:
-
-> File-type inference disabled by default
-
-Previously we automatically inferred spec type from a file location, this
-was a surprising behaviour for new users and undesirable for some veteran users
-so from RSpec 3 onwards this behaviour must be explicitly opted into with:
-
-```Ruby
-RSpec.configure do |config|
-  config.infer_spec_type_from_file_location!
-end
-```
-
-This change was made to accomplish our general goals of acting with the principle
-of least surprise and removing magic from RSpec. See [the directory structure
-documentation](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/directory-structure)
-for more details.
-
-The other `rspec-rails` specific change is:
+There are three particular `rspec-rails` specific changes to be aware of:
 
-> The default helper files created in RSpec 3.x have changed
+1. [The default helper files created in RSpec 3.x have changed](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#default-helper-files)
+2. [File-type inference disabled by default](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#file-type-inference-disabled)
+3. [Rails 4.x `ActiveRecord::Migration` pending migration checks](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#pending-migration-checks)
 
-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`.
+Please see the [RSpec Rails Upgrade
+docs](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade) for full
+details.
 
-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
+**NOTE:** Generators run in RSpec 3.x will now require `rails_helper` instead
+of `spec_helper`.
 
 ### Upgrading an Existing App
 
@@ -142,9 +122,6 @@ switch to the new helpers:
 
 ### 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.

features/.nav

@@ -1,8 +1,9 @@
+- upgrade:
+  - from_1x_to_2x.md (From rspec-rails-1.x to rspec-rails-2)
 - GettingStarted.md (Start from scratch)
 - Generators.md (Generators)
 - Transactions.md
 - Changelog.md
-- Upgrade.md
 - RailsVersions.md (Rails versions)
 - directory_structure.feature
 - model_specs:

features/upgrade/README.md

@@ -0,0 +1,157 @@
+# Upgrading from rspec-rails-2.x to rspec-rails-3
+
+For detailed information on the general RSpec 3.x upgrade process see the [RSpec
+Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
+
+There are several changes specific to `rspec-rails` to be aware of:
+
+- [Default helper files created in RSpec 3.x have changed](#default-helper-files)
+- [File-type inference disabled by default](#file-type-inference-disabled)
+- [Rails 4.x `ActiveRecord::Migration` pending migration checks](#pending-migration-checks)
+
+<a name="default-helper-files"></a>
+## 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
+
+<a name="generators"></a>
+### Generators
+
+Generators run in RSpec 3.x will require `rails_helper` and not `spec_helper`.
+
+<a name="upgrading-an-existing-app"></a>
+### 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 mv 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.
+
+<a name="file-type-inference-disabled"></a>
+## File-type inference disabled by default
+
+Previously we automatically inferred spec type from a file location, this
+was a surprising behaviour for new users and undesirable for some veteran users
+so from RSpec 3 onwards this behaviour must be explicitly opted into with:
+
+```Ruby
+RSpec.configure do |config|
+  config.infer_spec_type_from_file_location!
+end
+```
+
+This change was made to accomplish our general goals of acting with the principle
+of least surprise and making RSpec configuration more explicit. See [the
+directory structure documentation](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/directory-structure) for more details.
+
+<a name="pending-migration-checks"></a>
+## Rails 4.x `ActiveRecord::Migration` pending migration checks
+
+If you are not using `ActiveRecord` you do not need to worry about these
+settings.
+
+Users of Rails 4.x can now take advantage of improved schema migration and sync
+abilities. Prior to RSpec 3, users were required to manually run migrations in
+both the development and test environments. Additionally, the behavior differed
+depending on if the specs were run via `rake` or via the standalone `rspec`
+command.
+
+With the release of Rails 4, new APIs have been exposed on
+`ActiveRecord::Migration`. This allows RSpec to take advantage of these new
+standard migration checks, mirroring behavior across the board.
+
+  - Rails 4.0.x
+
+    Add the following to the top of the `rails_helper` file after Rails has
+    been required:
+
+    ```ruby
+    ActiveRecord::Migration.check_pending!
+    ```
+
+    This will raise an exception if there are any pending schema changes. Users
+    will still be required to manually keep the development and test
+    environments in sync.
+
+  - Rails 4.1+
+
+    With this release there was an exciting new feature. Users no longer need
+    to keep the development and test environments in sync. To take advantage of
+    this add the following to the top of the `rails_helper` file after Rails
+    has been required:
+
+    ```ruby
+    ActiveRecord::Migration.maintain_test_schema!
+    ```
+
+    What this does is that rather than just raising when the test schema has
+    pending migrations, Rails will try to load the schema. An exception will
+    now only be raised if there are pending migrations afterwards the schema
+    has been loaded.
+
+    There are a few caveates to be aware of when using this:
+
+      - Migrations still need to be run manually; although now this only has to
+        be done in the 'development' environment
+      - An exception will be raised If the schema has not been initialized. The
+        exception will provide instructions stating `rake db:migrate` needs to
+        be run.
+
+It is possible to opt-out of checking for pending migrations. Since this is
+actually a feature of Rails, the change needs to be done as part of the Rails
+configuration. To do this, add the following to your
+`config/environments/test.rb` file:
+
+```ruby
+config.active_record.maintain_test_schema = false
+```
+
+New RSpec projects don't need to worry about these commands as the `rails
+generate rspec:install` will add them automatically.

features/Upgrade.md → features/upgrade/from_1x_to_2x.md

@@ -1,74 +1,3 @@
-# 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 mv 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