Adds deprecations for event listener functionality

content/ember/v3/deprecate-inherit-function-listeners.md

@@ -0,0 +1,105 @@
+---
+id: events.inherited-function-listeners
+title: Inherited Function Listeners
+until: '3.9.0'
+since: 'Upcoming Features'
+---
+
+Currently, function listeners and string listeners are functionally indentical
+to each other. Their inheritance and removal structure is the same, and they can
+be used interchangeably for the most part. However, function listeners can be
+much more expensive as they maintain a reference to the function.
+
+Function listeners also have limited utility outside of _per instance_ usage.
+Consider the following example which the same listener using strings and using
+function references:
+
+```js
+class Foo {
+  method() {}
+}
+
+addListener(Foo, 'event', 'method');
+addListener(Foo, 'event', Foo.prototype.method);
+```
+
+It's clear that the string version is much more succinct and preferable. A more
+common alternative would be adding the listener to the instance in the
+constructor:
+
+```js
+class Foo {
+  constructor() {
+    addListener(this, 'event', this.method);
+  }
+
+  method() {}
+}
+```
+
+But in this case, inheritance is not needed either.
+
+## Updating
+
+In cases where function listeners have been added, and those functions _do_
+exist on the parent object, replace them with string listeners:
+
+Before:
+```js
+class Foo {
+  method() {}
+}
+
+addListener(Foo, 'event', Foo.prototype.method);
+```
+
+After:
+```js
+class Foo {
+  method() {}
+}
+
+addListener(Foo, 'event', 'method');
+```
+
+In cases where function listeners have been added for _arbitrary_ functions
+which do not exist on the parent object, you can convert the function to a
+method, create a wrapper function, or add the listener on the instance instead:
+
+Before:
+```js
+function foo() {}
+
+class Foo {}
+
+addListener(Foo, 'event', foo);
+```
+
+After:
+```js
+class Foo {
+  foo() {}
+}
+
+addListener(Foo, 'event', 'foo');
+
+// OR
+function originalFoo() {}
+
+class Foo {
+  foo() {
+    originalFoo();
+  }
+}
+
+addListener(Foo, 'event', 'foo');
+
+// OR
+function foo() {}
+
+class Foo {
+  constructor() {
+    addListener(this, 'event', foo);
+  }
+}
+```

content/ember/v3/deprecate-remove-all-listeners.md

@@ -0,0 +1,39 @@
+---
+id: events.remove-all-listeners
+title: Remove All Listeners/Observers
+until: '3.9.0'
+since: 'Upcoming Features'
+---
+
+When using both the `removeListener` and `removeObserver` methods, users can
+omit the final string or method argument to trigger an undocumented codepath
+that will remove _all_ event listeners/observers for the given key:
+
+```js
+let foo = {
+  method1() {}
+  method2() {}
+};
+
+addListener(foo, 'init', 'method1');
+addListener(foo, 'init', 'method2');
+
+removeListener(foo, 'init');
+```
+
+This functionality will be removed since it is uncommonly used, undocumented,
+and adds a fair amount of complexity to a critical path. To update, users should
+remove each listener individually:
+
+```js
+let foo = {
+  method1() {}
+  method2() {}
+};
+
+addListener(foo, 'init', 'method1');
+addListener(foo, 'init', 'method2');
+
+removeListener(foo, 'init', 'method1');
+removeListener(foo, 'init', 'method2');
+```