Add Upgrading guide [ci skip]

History.md

@@ -43,7 +43,7 @@ Release date: 2018-03-02
 ### Removed
 
 * Ruby < 2.2.2 support
-* `Capybara.exact_options` no longer exists. Just use `exact:true` on relevant actions/finders if necessary.
+* `Capybara.exact_options` no longer exists. Just use `exact: true` on relevant actions/finders if necessary.
 * All previously deprecated methods removed
 * RSpec 2.x support
 * selenium-webdriver 2.x support

README.md

@@ -76,7 +76,7 @@ GitHub): http://groups.google.com/group/ruby-capybara
 
 ## <a name="setup"></a>Setup
 
-Capybara requires Ruby 2.2.0 or later. To install, add this line to your
+Capybara requires Ruby 2.2.2 or later. To install, add this line to your
 `Gemfile` and run `bundle install`:
 
 ```ruby
@@ -151,15 +151,15 @@ If you are using Rails, put your Capybara specs in `spec/features` or `spec/syst
 if [you have it configured in
 RSpec](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#file-type-inference-disabled))
 and if you have your Capybara specs in a different directory, then tag the
-example groups with `:type => :feature` or `:type => :system` depending on which type of test you're writing.
+example groups with `type: :feature` or `type: :system` depending on which type of test you're writing.
 
 If you are not using Rails, tag all the example groups in which you want to use
-Capybara with `:type => :feature`.
+Capybara with `type: :feature`.
 
 You can now write your specs like so:
 
 ```ruby
-describe "the signin process", :type => :feature do
+describe "the signin process", type: :feature do
   before :each do
     User.make(email: 'user@example.com', password: 'password')
   end
@@ -183,7 +183,7 @@ to one specific driver. For example:
 ```ruby
 describe 'some stuff which requires js', js: true do
   it 'will use the default js driver'
-  it 'will switch to one specific driver', :driver => :webkit
+  it 'will switch to one specific driver', driver: :webkit
 end
 ```
 
@@ -219,7 +219,7 @@ feature "Signing in" do
 end
 ```
 
-`feature` is in fact just an alias for `describe ..., :type => :feature`,
+`feature` is in fact just an alias for `describe ..., type:> :feature`,
 `background` is an alias for `before`, `scenario` for `it`, and
 `given`/`given!` aliases for `let`/`let!`, respectively.
 

UPGRADING.md

@@ -0,0 +1,19 @@
+# Upgrading from Capybara 2.x to 3.x
+
+
+## Finders
+
+The biggest user differences between Capybara 2.x and 3.x are the changes in behavior of `first` and `all`. In Capybara 2.x both methods would, by default, return immediately with nil if no matching elements exist on the page.  In Capybara 3.x this has changed to include the waiting/retrying behavior found in the other Capybara finders and matchers.
+
+`first` will now wait up to `Capybara.default_max_wait_time` seconds for at least one matching element to exist, and return the first matching element.  If no matching elements are found within the time it will now raise a `Capybara::ElementNotFound` error instead of returning nil. If you need to maintain the previous behavior you can pass `minimum: 0` as an option to `first`
+
+```ruby
+first('div', minimum: 0)
+```
+
+`all` will now wait up to `Capybara.default_max_wait_time' seconds for at least one matching element to exist, and return the matching elements.  If no matching elements are found within the time it will return an empty result set.  If you need to maintain the previous behavior you can pass `wait: false` as an option to `all`
+
+```ruby
+all('div', wait: false)
+```
+