mention upgrading in readme

README.md

@@ -10,6 +10,7 @@ Heavy metal SOAP client
 [![Code Climate](https://codeclimate.com/github/savonrb/savon.svg)](https://codeclimate.com/github/savonrb/savon)
 [![Coverage Status](https://coveralls.io/repos/savonrb/savon/badge.svg)](https://coveralls.io/r/savonrb/savon)
 
+If you're reading this on GitHub, note that this README is for the main branch and that features/changes described here might not correspond to your version. You can find the documentation for your release [at rubydoc.info](https://www.rubydoc.info/find/gems?q=savon).
 
 ## Installation
 
@@ -52,6 +53,10 @@ response.body
 For more examples, you should check out the
 [integration tests](https://github.com/savonrb/savon/tree/version2/spec/integration).
 
+## Upgrading from v2.x to v3.x
+
+See [UPGRADING.md](UPGRADING.md) for more information.
+
 ## Ruby version support
 
 Every savon release is tested with contemporary supported versions of ruby. Historical compatibility information:

UPGRADING.md

@@ -1,6 +1,6 @@
 # Upgrading from v2.x to v3.x
 
-Savon 3 is a major release that replaces its HTTP transport client, [HTTPI](https://github.com/savonrb/httpi) with [Faraday](https://lostisland.github.io/faraday), introducing major breaking changes.
+Savon 3 replaces its HTTP transport client, [HTTPI](https://github.com/savonrb/httpi) with [Faraday](https://lostisland.github.io/faraday), introducing major breaking changes.
 
 While this brings significant new features and improvements, it also removes or changes some existing features and options.
 
@@ -12,7 +12,7 @@ These options are no longer supported, as Faraday does not directly support them
 
 Resolution: 
 
-For `ssl_cert_key_file` and `ssl_cert_key_password` open and decrypt the client key using OpenSSL, and provide the result as the `ssl_cert_key` option instead.
+For `ssl_cert_key_file` and `ssl_cert_key_password` open and decrypt the client key using OpenSSL, and provide the `OpenSSL::PKey::RSA, OpenSSL::PKey::DSA` as the `ssl_cert_key` option instead.
 
 For `ssl_cert_file` pass the `OpenSSL::X509::Certificate` as the `ssl_cert` option instead.