Merge pull request emberjs#2600 from bmeurant/master

Add Enumerable.contains to deprecation guide

source/deprecations/v2.x.html.md

@@ -654,3 +654,74 @@ export default Ember.Component.extend({
 If you're an addon maintainer, there is a polyfill for safe string detection ([ember-string-ishtmlsafe-polyfill](https://github.com/workmanw/ember-string-ishtmlsafe-polyfill))
 that will help maintain backwards compatibility. Additionally, it's worth noting that `Ember.String.htmlSafe`
 is supported back to pre-1.0, so there should be no concerns of backwards compatibility there.
+
+#### Enumerable#contains
+
+##### until: 3.0.0
+##### id: ember-runtime.enumerable-contains
+
+The `Enumerable#contains` and `Array#contains` methods were deprecated in favor of `Enumerable#includes` and `Array#includes` 
+to stay in line with ES standards. See [RFC](https://github.com/emberjs/rfcs/blob/master/text/0136-contains-to-includes.md) for details.
+
+`contains` and `includes` have similar behaviors. A notable exception is how `NaN` values are handled.
+`contains` uses [Strict equality comparison algorithm](https://tc39.github.io/ecma262/2016/#sec-strict-equality-comparison)
+for testing inclusion while `includes` uses [SameValueZero algorithm](https://tc39.github.io/ecma262/2016/#sec-samevaluezero).
+
+Before:
+
+```js
+var arr = ['a', 'b', 'c', NaN, undefined, null];
+arr.contains('b');        // true
+arr.contains('d');        // false
+arr.contains(NaN);        // false
+arr.contains(null);       // false
+arr.contains(undefined);  // false
+```
+
+After:
+
+```js
+var arr = ['a', 'b', 'c', NaN, undefined, null];
+arr.includes('b');        // true
+arr.includes('d');        // false
+arr.includes(NaN);        // true
+arr.contains(null);       // true
+arr.contains(undefined);  // true
+```
+
+`includes` also allows a second optional parameter `startAt` to specify the index at which to begin searching:
+
+```js
+var arr = ['a', 'b', 'c', NaN];
+arr.includes('c', 2);   // true
+arr.includes('c', -2);  // true
+```
+
+Note that the second `startAt` parameter is only available for `Ember.Array` because `Ember.Enumerable` does not rely on index-ordered access.
+
+`Enumerable#without` and `MutableEnumerable#addObject` use now internally `includes` instead of `contains`. This leads to some minor breaking changes:
+
+Before:
+
+```js
+var arr = ['a', 'b'];
+
+arr.addObject(NaN);       // ['a', 'b', NaN] 
+arr.addObject(NaN);       // ['a', 'b', NaN, NaN] 
+arr.without(NaN);         // ['a', 'b', NaN, NaN] 
+```
+
+After:
+
+```js
+var arr = ['a', 'b'];
+
+var arr = ['a', 'b'];
+
+arr.addObject(NaN);       // ['a', 'b', NaN] 
+arr.addObject(NaN);       // ['a', 'b', NaN] 
+arr.without(NaN);         // ['a', 'b'] 
+```
+ 
+
+Added in [PR #13553](https://github.com/emberjs/ember.js/pull/13553).