diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md
new file mode 100644
index 0000000000..829eb016a2
--- /dev/null
+++ b/UPGRADE-3.0.md
@@ -0,0 +1,47 @@
+UPGRADE FROM 2.x to 3.0
+=======================
+
+### Routing
+
+ * Some route settings have been renamed:
+
+ * The `pattern` setting for a route has been deprecated in favor of `path`
+ * The `_scheme` and `_method` requirements have been moved to the `schemes` and `methods` settings
+
+ Before:
+
+ ```
+ article_edit:
+ pattern: /article/{id}
+ requirements: { '_method': 'POST|PUT', '_scheme': 'https', 'id': '\d+' }
+
+
+ POST|PUT
+ https
+ \d+
+
+
+ $route = new Route();
+ $route->setPattern('/article/{id}');
+ $route->setRequirement('_method', 'POST|PUT');
+ $route->setRequirement('_scheme', 'https');
+ ```
+
+ After:
+
+ ```
+ article_edit:
+ path: /article/{id}
+ methods: [POST, PUT]
+ schemes: https
+ requirements: { 'id': '\d+' }
+
+
+ \d+
+
+
+ $route = new Route();
+ $route->setPath('/article/{id}');
+ $route->setMethods(array('POST', 'PUT'));
+ $route->setSchemes('https');
+ ```