Add note with the only breaking change in Ember 2.0: Ember.set

source/deprecations/v1.x.html.md

@@ -1153,4 +1153,65 @@ This makes it possible to express a number of concepts directly in the template
 
 Ember 1.13 deprecated `bind-attr` in favor of the new syntax.
 
-To aid in the migration, you can use the [legacy-bind-attr plugin](https://github.com/emberjs/legacy-bind-attr) to restore this behavior in Ember 2.0 and silence the deprecation warning.
+To aid in the migration, you can use the [legacy-bind-attr plugin](https://github.com/emberjs/legacy-bind-attr) to restore this behavior in Ember 2.0 and silence the deprecation warning.
+
+
+### Breaking Change in Ember 2.0: Return value of Ember.set
+
+
+Ember 2.0 contains **only one** breaking change that was impossible to deprecate in advance.
+
+In Ember 1.X `Ember.set` and `this.set` returned the object you were setting a property on, so
+you could chain it. 
+
+Per example:
+
+```js
+this.set('age', 3).get('name'); // "Tomster"
+```
+
+Starting in Ember 2.0, `set` return the property being set.
+
+```js
+this.set('age', 3); // return 3, as expected.
+```
+
+The rationale behind this change is to be aliged with the way ES5 getters and setters work.
+The ultimate goal is to make ember code as conventional and approachable as possible, making
+also some usages of computed properties more natural and enabling the usage of `_super` from within
+setters:
+
+```js
+var TwitterUser = Ember.Object.extend({
+  handler: 'Tomster',
+
+  aka: Ember.computed('handler', {
+    get() {
+      return this.get('handler');
+    },
+    set(_, v) {
+      return this.set('handler', v);
+    }
+  })
+});
+
+var TwitterTroll = TwitterUser.extend({
+  aka: Ember.computed('handler', {
+    get() {
+      return this.get('handler') + ' LOL';
+    },
+    set() {
+      return this._super(...arguments);
+    }
+  })  
+});
+
+var troll = TwitterTroll.create();
+
+troll.get('aka'); // "Tomster"
+
+troll.set('aka', 'HorseJS'); // In ember 1.X this returns the `troll` instance, while in Ember 2.0 it returns "HorseJS"
+
+troll.get('aka'); // Also, since the return value of the call to `_super` has been cached, 
+                  // in Ember 1.X this has cached the `troll` instance, while in ember 2.0 returns "HorseJS"
+```