Merge pull request #2342 from rspec/drop-rails-3-docs

Drop outdated documentation

Author: JonRowe

features/.nav

@@ -1,5 +1,3 @@
-- 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

features/GettingStarted.md

@@ -1,15 +1,15 @@
-Install Rails-3
+Install Rails 6
 
-    $ gem install rails -v "~> 3.0.0"
+    $ gem install rails -v "~> 6.0.0"
 
 ### Generate an app
 
-    $ rails new example
-    $ cd example
+    $ rails new example_app
+    $ cd example_app
 
 ### Add rspec-rails to the Gemfile
 
-    $ echo 'gem "rspec-rails", :group => [:development, :test]' >> Gemfile
+    $ echo 'gem "rspec-rails", group: [:development, :test]' >> Gemfile
 
 ### Install the bundle
 
@@ -29,7 +29,7 @@ the files in the `spec` directory to RSpec.
 
 ### Run migrations
 
-    $ rake db:migrate && rake db:test:prepare
+    $ rails db:migrate && rails db:test:prepare
 
 ### Run RSpec
 

features/RailsVersions.md

@@ -1,4 +1,5 @@
     rails version | rspec-rails version
+    ------------- | -------------------
     2.3           | 1.3.4
     3.0           | >= 2.0
     3.1           | >= 2.6
@@ -8,3 +9,5 @@
     4.2           | >= 3.1
     5.0           | >= 3.5
     5.1           | >= 3.6
+    5.2           | >= 3.8
+    6.0           | >= 4.0

features/directory_structure.feature

@@ -63,7 +63,7 @@ Feature: Directory Structure
   their location on the filesystem. This was both confusing to new users and not
   desirable for some veteran users.
 
-  In RSpec 3, this behavior must be explicitly enabled:
+  This behaviour must be explicitly enabled:
 
   ```ruby
   ​# spec/rails_helper.rb

features/upgrade/README.md

@@ -1,178 +1,7 @@
-# Upgrading from rspec-rails-2.x to rspec-rails-3
+# Upgrading from rspec-rails 3.x to version 4
 
-For detailed information on the general RSpec 3.x upgrade process see the [RSpec
-Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
+RSpec Rails 4 is a major version under semantic versioning, it allowed us to change the supported Rails versions to 5 and 6 only. There are no changes required to upgrade to RSpec Rails 4 if you are using Rails 5 or 6.
 
-There are several changes specific to `rspec-rails` to be aware of:
+If you are using Rails 4.2 you can use RSpec Rails 4, but note that support for it is not maintained, we consider this a breaking change hence the version change, and you must be on Ruby 2.2 as a minimum.
 
-- [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)
-
-- [Extraction of `stub_model` and `mock_model` to `rspec-activemodel-mocks`](#extract-stub-model)
-
-<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.
-
-<a name="extract-stub-model"></a>
-## Extraction of `stub_model` and `mock_model` to [`rspec-activemodel-mocks`](https://github.com/rspec/rspec-activemodel-mocks)
-
-Historically, `stub_model` and `mock_model` have been difficult to maintain.
-They are tightly coupled to `ActiveRecord` which isn't always the ORM of choice.
-This maintainence coupling has lead to delays with previous releases.
-Additionally, the objects generated by these methods hide important
-`ActiveRecord` behavior complexity which would otherwise be good to expose.
-
-Some alternatives are:
-
-- Wrap calls to `ActiveRecord` objects in more specific domain models and
-  services
-- Use new unsaved `ActiveRecord` instances (e.g. `Model.new`)
-- Consider [partial mocks](https://www.relishapp.com/rspec/rspec-mocks/docs/basics/partial-test-doubles) on an `ActiveRecord` instance
-- Let the specs hit database directly where appropriate
+If you are upgrading from an earlier version of RSpec Rails, please consult [the upgrading 2.x to 3.x guide](https://relishapp.com/rspec/rspec-rails/v/3-9/docs/upgrade).