From 0899c228b3d730a0a56e41c98f56d6712470b0b5 Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Fri, 12 Feb 2021 14:49:30 +0000
Subject: [PATCH] docs: add a migration entry for renaming `hook:` to `vnode-`

---
 src/.vuepress/config.js                       |  1 +
 src/guide/migration/introduction.md           |  1 +
 src/guide/migration/vnode-lifecycle-events.md | 48 +++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 src/guide/migration/vnode-lifecycle-events.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 6ed9cc426a..1cf2e3befd 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -203,6 +203,7 @@ const sidebar = {
         '/guide/migration/v-model',
         '/guide/migration/v-if-v-for',
         '/guide/migration/v-bind',
+        '/guide/migration/vnode-lifecycle-events',
         '/guide/migration/watch'
       ]
     }
diff --git a/src/guide/migration/introduction.md b/src/guide/migration/introduction.md
index a54ba52d9b..d12365c8a6 100644
--- a/src/guide/migration/introduction.md
+++ b/src/guide/migration/introduction.md
@@ -105,6 +105,7 @@ The following consists a list of breaking changes from 2.x:
 - [When watching an array, the callback will only trigger when the array is replaced. If you need to trigger on mutation, the `deep` option must be specified.](/guide/migration/watch.html)
 - `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
 - In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead - this means the container itself is no longer considered part of the template.
+- [Lifecycle `hook:` events prefix changed to `vnode-`](/guide/migration/vnode-lifecycle-events.html)
 
 ### Removed APIs
 
diff --git a/src/guide/migration/vnode-lifecycle-events.md b/src/guide/migration/vnode-lifecycle-events.md
new file mode 100644
index 0000000000..6642f63adf
--- /dev/null
+++ b/src/guide/migration/vnode-lifecycle-events.md
@@ -0,0 +1,48 @@
+---
+badges:
+  - breaking
+---
+
+# VNode Lifecycle Events <MigrationBadges :badges="$frontmatter.badges" />
+
+## Overview
+
+In Vue 2, it was possible to use events to listen for key stages in a component's lifecycle. These events had names that started with the prefix `hook:`, followed by the name of the corresponding lifecycle hook.
+
+In Vue 3, this prefix has been changed to `vnode-`. In addition, these events are now available for HTML elements as well as components.
+
+## 2.x Syntax
+
+In Vue 2, the event name is the same as the equivalent lifecycle hook, prefixed with `hook:`:
+
+```html
+<template>
+  <child-component @hook:updated="onUpdated">
+</template>
+```
+
+## 3.x Syntax
+
+In Vue 3, the event name is prefixed with `vnode-`:
+
+```html
+<template>
+  <child-component @vnode-updated="onUpdated">
+</template>
+```
+
+Or just `vnode` if you're using camel case:
+
+```html
+<template>
+  <child-component @vnodeUpdated="onUpdated">
+</template>
+```
+
+## Migration Strategy
+
+In most cases it should just require changing the prefix. The lifecycle hooks `beforeDestroy` and `destroyed` have been renamed to `beforeUnmount` and `unmounted` respectively, so the corresponding event names will also need to be updated.
+
+## See also
+
+- [Migration guide - Events API](/guide/migration/events-api.html)