diff --git a/README.md b/README.md
index ed25eb240..4c6f95751 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ proxies and load balancers.
  	<img src="https://coveralls.io/repos/nodejitsu/node-http-proxy/badge.png?branch=caronte"/></a>
 </p>
 
+## Looking to Upgrade from 0.8.x ? Click [here](UPGRADING.md)
+
 ### Core Concept
 
 A new proxy is created by calling `createProxyServer` and passing
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 000000000..8fb525c61
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,26 @@
+`caronte` is a from-scratch implementation of `http-proxy` and, as such
+brings some breaking changes to APIs.
+
+## Server creation
+
+Available through `.createServer()` or `.createProxyServer()`.
+Check the README.md for a more detailed explanation of the parameters.
+
+## Proxying
+
+Web proying is done by calling the `.web()` method on a Proxy instance. Websockets
+are proxied by the `.ws()` method.
+
+## Error Handling
+
+It is possible to listen globally on the `error` event on the server. In alternative, a 
+callback passed to `.web()` or `.ws()` as last parameter is also accepted.
+
+## Dropped
+
+Since the API was rewritten to be extremely flexible we decided to drop some features 
+which were in the core and delegate them to eventual "user-land" modules.
+
+- Middleware API
+- ProxyTable API
+