README.md in slop-4.0.0 vs README.md in slop-4.1.0

@@ -44,10 +44,11 @@
 
 ```ruby
 o.string  #=> Slop::StringOption, expects an argument
 o.bool    #=> Slop::BoolOption, no argument, aliased to BooleanOption
 o.integer #=> Slop::IntegerOption, expects an argument, aliased to IntOption
+o.float   #=> Slop::FloatOption, expects an argument
 o.array   #=> Slop::ArrayOption, expects an argument
 o.null    #=> Slop::NullOption, no argument and ignored from `to_hash`
 o.on      #=> alias for o.null
 ```
 
@@ -246,5 +247,87 @@
 
 As of version 4, Slop does not have built in support for git-style subcommands.
 You can use version 3 of Slop (see `v3` branch). I also expect there to be some
 external libraries released soon that wrap around Slop to provide support for
 this feature. I'll update this document when that happens.
+
+Upgrading from version 3
+------------------------
+
+Slop v4 is completely non-backwards compatible. The code has been rewritten
+from the group up. If you're already using version 3 you have *have* to update
+your code to use version 4. Here's an overview of the more fundamental changes:
+
+#### No more `instance_eval`
+
+Before:
+
+```ruby
+Slop.parse do
+  on 'v', 'version' do
+    puts VERSION
+  end
+end
+```
+
+After:
+
+```ruby
+Slop.parse do |o|
+  o.on '-v', '--version' do
+    puts VERSION
+  end
+end
+```
+
+#### No more `as` for option types
+
+Instead, the type is declared in the method call. Before:
+
+```ruby
+on 'port=', as: Integer
+```
+
+After:
+
+```ruby
+o.int '--port' # or integer
+```
+
+See the custom types section of the document.
+
+#### No more trailing `=`
+
+Instead, the "does this option expect an argument" question is answered by
+the option type (i.e `on` and `bool` options do not expect arguments, all
+others do. They handle type conversion, too.
+
+#### Hyphens are required
+
+This was a hard decision to make, but you must provide prefixed hyphens when
+declaring your flags. This makes the underlying code much nicer and much less
+ambiguous, which leads to less error prone code. It also means you can easily
+support single hyphen prefix for a long flag, i.e `-hostname` which you
+could not do before. It also provides a hidden feature, which is infinity flag
+aliases: `o.string '-f', '-x', '--foo', '--bar', 'this is insane'`
+
+#### Strict is now on by default
+
+v3 had a `strict` option. v4 has no such option, and to suppress errors you can
+instead provide the `suppress_errors: true` option to Slop.
+
+#### No more parse!
+
+Where v3 has both `Slop.parse` and `Slop.parse!`, v4 only has `parse`. The
+former was used to decide whether Slop should or should not mutate the
+original args (usually ARGV). This is almost never what you want, and it
+can lead to confusion. Instead, `Slop::Result` provides an `arguments`
+methods:
+
+```ruby
+opts = Slop.parse do |o|
+  o.string '--hostname', '...'
+end
+
+# ARGV is "hello --hostname foo bar"
+p opts.arguments #=> ["hello", "bar"]
+```