diff --git a/packages/docs/guide/migration/index.md b/packages/docs/guide/migration/index.md
index 1f841c89e..6fb85383b 100644
--- a/packages/docs/guide/migration/index.md
+++ b/packages/docs/guide/migration/index.md
@@ -443,6 +443,12 @@ Given any [normalized route location](/api/#RouteLocationNormalized):
 
 **Reason**: This allows to easily copy existing properties of a location when calling `router.push()` and `router.resolve()`, and make the resulting route location consistent across browsers. `router.push()` is now idempotent, meaning that calling `router.push(route.fullPath)`, `router.push({ hash: route.hash })`, `router.push({ query: route.query })`, and `router.push({ params: route.params })` will not create extra encoding.
 
+### `$router.push()` and `$router.replace()` - `onComplete` and `onAbort` callbacks
+
+Previously, `$router.push()` and `$router.replace()` accepted two callbacks, `onComplete` and `onAbort`, as second and third arguments. They were called after a navigation based on the result. With the introduction of a Promise based API, these callbacks are redundant and have been removed. See [Navigation Failures](/guide/advanced/navigation-failures.md) for more information on how to detect successful and failed navigations.
+
+**Reason**: Reduce library size by adapting to established JS standards (Promises).
+
 ### TypeScript changes
 
 To make typings more consistent and expressive, some types have been renamed: