From f0bddb6abb6812077472b84dcd52c753ab93c740 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 14 Jul 2020 15:11:13 +0300
Subject: [PATCH 1/2] feat: added events api section

---
 src/.vuepress/config.js           |  3 +-
 src/guide/migration/events-api.md | 64 +++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 src/guide/migration/events-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index af6106dce0..4c840a30c3 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -93,7 +93,8 @@ const sidebar = {
         'migration/v-model',
         'migration/functional-components',
         'migration/async-components',
-        'migration/custom-directives'
+        'migration/custom-directives',
+        'migration/events-api'
       ]
     },
     {
diff --git a/src/guide/migration/events-api.md b/src/guide/migration/events-api.md
new file mode 100644
index 0000000000..8b8df7a69d
--- /dev/null
+++ b/src/guide/migration/events-api.md
@@ -0,0 +1,64 @@
+---
+types:
+  - removed
+  - breaking
+---
+
+# `$on`, `$off` and `$once` methods removal <span v-for="type in $frontmatter.types" class="badge" :key="`type-${type}`">{{ type }}</span>
+
+## Overview
+
+`$on`, `$off` and `$once` instance methods are removed. Vue instances no longer implement the event emitter interface.
+
+## Previous Syntax
+
+In v2, Vue instance could be used to trigger handlers attached imperatively via the event emitter API (`$on`, `$off` and `$once`). This was used to create _event hubs_ to create global event listeners used across the whole application:
+
+```js
+// eventHub.js
+
+const eventHub = new Vue()
+
+export default eventHub
+```
+
+```js
+// ChildComponent.vue
+import eventHub from './eventHub'
+
+export default {
+  mounted() {
+    // adding eventHub listener
+    eventHub.$on('custom-event', () => {
+      console.log('Custom event triggered!')
+    })
+  },
+  beforeDestroy() {
+    // removing eventHub listener
+    eventHub.$off('custom-event')
+  }
+}
+```
+
+```js
+// ParentComponent.vue
+import eventHub from './eventHub'
+
+export default {
+  methods: {
+    callGlobalCustomEvent() {
+      eventHub.$emit('custom-event') // if ChildComponent is mounted, we will have a message in the console
+    }
+  }
+}
+```
+
+## 3.x Update
+
+We removed `$on`, `$off` and `$once` methods from Vue instance completely. `$emit` is still a part of the existing API as it's used to trigger event handlers declaratively attached by a parent component
+
+## How to Migrate
+
+Existing event hubs can be replaced by using an external library implementing the event emitter interface, for example [mitt](https://github.com/developit/mitt).
+
+These methods can also be supported in compatibility builds.

From 933d464392fd2ba934925df42c3d3a82f80d9add Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 14 Jul 2020 16:42:53 +0300
Subject: [PATCH 2/2] fix: renamed section to Migration Strategy

---
 src/guide/migration/events-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/migration/events-api.md b/src/guide/migration/events-api.md
index 8b8df7a69d..bc3c89e3da 100644
--- a/src/guide/migration/events-api.md
+++ b/src/guide/migration/events-api.md
@@ -57,7 +57,7 @@ export default {
 
 We removed `$on`, `$off` and `$once` methods from Vue instance completely. `$emit` is still a part of the existing API as it's used to trigger event handlers declaratively attached by a parent component
 
-## How to Migrate
+## Migration Strategy
 
 Existing event hubs can be replaced by using an external library implementing the event emitter interface, for example [mitt](https://github.com/developit/mitt).