Upgrading instructions to 3.0

Advanced Usage.md

@@ -378,7 +378,7 @@ function routeLoaded(event) {
 </script>
 ````
 
-For help with the `wrap` function, check the [route pre-conditions](#route-pre-conditions) section.
+For help with the `wrap` function, check the [route wrapping](#route-wrapping) section.
 
 > **Note:** When using minifiers such as terser, the name of Svelte components might be altered by the minifier. As such, it is recommended to use custom user data to identify the component who caused the pre-condition failure, rather than relying on the `detail.name` property. The latter, might contain the minified name of the class.
 

Router.svelte

@@ -15,7 +15,7 @@ import {wrap as _wrap} from './wrap'
 export function wrap(route, userData, ...conditions) {
     // Use the new wrap method and show a deprecation warning
     // eslint-disable-next-line no-console
-    console.warn('Method `wrap` from `svelte-spa-router` is deprecated and will be removed in a future version. Please use `svelte-spa-router/wrap` instead. See https://bit.ly/2ZQpype')
+    console.warn('Method `wrap` from `svelte-spa-router` is deprecated and will be removed in a future version. Please use `svelte-spa-router/wrap` instead. See http://bit.ly/svelte-spa-router-upgrading')
     return _wrap({
         route,
         userData,

UPGRADING.md

@@ -1,5 +1,79 @@
 # Upgrading instructions
 
+## Upgrading to 3.x
+
+When upgrading from svelte-spa-router 2.x to 3.x, please note the following breaking changes:
+
+### URL parameters are now automatically decoded
+
+Params that are extracted from the URL are now automatically decoded, as per [this issue](https://github.com/ItalyPaleAle/svelte-spa-router/issues/107).
+
+For example, if you have a route similar to `/book/:name` and your users navigate to `/book/dante%27s%20inferno`:
+
+- ❌ The **old** behavior (svelte-spa-router 2 and older) was to assign `dante%27s%20inferno` to `params.name`
+- ✅ The **new** behavior in svelte-spa-router 3 is to assign `dante's inferno` to `params.name`
+
+This is done by invoking [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent).
+
+If your application was decoding URL parameters before, remove that invocation when updating to svelte-spa-router 3.
+
+### New `wrap` method
+
+The `wrap` method exported by `svelte-spa-router` has been deprecated. Even though it remains available and functional (albeit showing a warning), it will be removed in a later version of the router.
+
+Please use the new `wrap` method exported by `svelte-spa-router/wrap` instead. This method's signature accepts a single argument which is an object of properties. It adds support for many other features too, such as dynamically-imported routes.
+
+To learn more about the new `wrap` method and its features, check out the documentation on [Route wrapping](/Advanced%20Usage.md#route-wrapping).
+
+To upgrade, maintaining the same functionality:
+
+❌ Version 2.x:
+
+````js
+// Old import path
+import {wrap} from 'svelte-spa-router'
+
+const routes = {
+    // Method signature: wrap(route, userData, ...conditions)
+    '/foo': wrap(
+        // Component
+        Foo,
+        // Custom data
+        {foo: 'bar'},
+        // Pre-condition function
+        (detail) => {
+            // ...
+        },
+        // ...more pre-condition functions
+    )
+}
+````
+
+✅ Version 3.x:
+
+````js
+// New import path
+import {wrap} from 'svelte-spa-router/wrap'
+
+const routes = {
+    // Method signature: wrap(options)
+    '/foo': wrap({
+        // Component
+        route: Foo,
+        // Custom data
+        customData: {foo: 'bar'},
+        // Pre-condition function
+        conditions: [
+            (detail) => {
+                // ...
+            },
+             // ...more pre-condition functions
+        ]
+        // See the documentation for the other possible properties for wrap
+    })
+}
+````
+
 ## Upgrading to 2.x
 
 When upgrading from svelte-spa-router 1.x to 2.x, please note the following breaking changes: