add note on object equality

text/0000-add-equality-operators.md

@@ -56,6 +56,112 @@ In addition to documenting the new helpers in the API docs, the Guides should be
 over computed properties where it makes more sense, adding illustrative examples and stressing out where
 the definition of truthiness of handlebars differs from the one of Javascript.
 
+### Note on Object Equality
+
+We should also add an additional section to the guides or API docs which discusses using object equality in templates.
+In general, object equality in JavaScript can be tricky. There are times when it makes perfect sense, for instance finding
+out if an item is the currently selected item in a list:
+
+```js
+class MySelect extends Component {
+  items = [{ value: 1 }, { value: 2 }, { value: 3 }];
+
+  @tracked selectedItem = this.items[0];
+
+  isSelected(item) {
+    item === this.selectedItem;
+  }
+}
+```
+
+The `{{eq}}` helper can be used in a similar way in templates:
+
+```hbs
+<select>
+  {{#each this.items as |item|}}
+    <option selected={{eq item this.selectedItem}}>
+      {{item.value}}
+    </option>
+  {{/each}}
+</select>
+```
+
+There are many valid use cases for object equality. However, there are also times when object equality is not guaranteed,
+especially in cases where it would have been in Classic Ember. Consider this component:
+
+```js
+class MyComponent extends Component {
+  @computed('foo')
+  get someObj() {
+    return { foo: this.foo }
+  }
+
+  checkEqual() {
+    return this.someObj === this.someObj;
+  }
+}
+```
+
+`checkEqual` will return `true`, because `@computed` _caches_ the object itself, and returns the same object every time unless `foo`
+changes. With Ember Octane, though, by default getters are not cached:
+
+```js
+class MyComponent extends Component {
+  get someObj() {
+    return { foo: this.foo }
+  }
+
+  checkEqual() {
+    return this.someObj === this.someObj;
+  }
+}
+```
+
+Now, the `someObj` getter will rerun every time the property is accessed, returning a _new_ object every time. `checkEqual` will
+now always return `false`, since the objects are not equal to each other.
+
+Now, we can do the same thing in a template with `eq`:
+
+```js
+{{eq this.someObj this.someObj}}
+```
+
+And the result depends here on Ember template's caching strategy. Ember only accesses a given property _once_, and then it caches
+the result, so this will return `true`. However, the semantics of template caches are not guaranteed, and in time may change, so relying
+on object equality in this way is not generally a good pattern.
+
+Even if the semantics do not change, there are still observable ways that users can trigger the getter twice and generate another object.
+For instance:
+
+```js
+class MyComponent extends Component {
+  get someObj() {
+    return { foo: this.foo }
+  }
+
+  get someObjAlias() {
+    return this.someObj;
+  }
+}
+```
+
+```hbs
+{{eq this.someObj this.someObjAlias}}
+```
+
+Overall, the point here is that if users expect an object generated by a getter or helper to remain _stable_ between accesses, such that
+object equality or state can be valid, then the user should explicitly cache that value themselves. This can be accomplished in a number
+of ways, one option being the proposed `@cached` decorator:
+
+```js
+class MyComponent extends Component {
+  @cached
+  get someObj() {
+    return { foo: this.foo }
+  }
+}
+```
+
 ## Drawbacks
 
 Adding new helpers increases the surface area of the framework and the code the core team commits to support long term.