From e73fef4d0bf8833e740cfc0e2e9ef3c18dd72d93 Mon Sep 17 00:00:00 2001
From: Igor Minar <igor@angular.io>
Date: Tue, 25 May 2021 17:24:41 -0700
Subject: [PATCH] docs: add a note about <select> and nested <option>s in Ivy
 compat guide (#42338)

An internal change in Ivy has surfaced issues in previosly broken code. This change adds a note to the
Ivy compatibility guide as well as the TrackByFunction api docs.

Fixes #35896

PR Close #42338
---
 aio/content/guide/ivy-compatibility.md              | 13 +++++++++----
 .../change_detection/differs/iterable_differs.ts    |  2 ++
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/aio/content/guide/ivy-compatibility.md b/aio/content/guide/ivy-compatibility.md
index bef52df361..0db0b561eb 100644
--- a/aio/content/guide/ivy-compatibility.md
+++ b/aio/content/guide/ivy-compatibility.md
@@ -85,7 +85,12 @@ For more information about the updated style precedence in Ivy, refer to the [st
 * If selecting the native `<option>` element in a `<select>` where the `<option>`s are created using `*ngFor`, use the `[selected]` property of an `<option>` instead of binding to the `[value]` property of the `<select>` element (previously, you could bind to either.) [details](guide/ivy-compatibility-examples#select-value-binding)
 
 * Embedded views (such as ones created by `*ngFor`) are now inserted in front of anchor DOM comment node (for example, `<!--ng-for-of-->`) rather than behind it as was the case previously.
-In most cases this does not have any impact on rendered DOM.
-In some cases (such as animations delaying the removal of an embedded view) any new embedded views will be inserted after the embedded view being animated away.
-This difference only last while the animation is active, and might alter the visual appearance of the animation.
-Once the animation is finished the resulting rendered DOM is identical to that rendered with View Engine.
+  In most cases this has no impact on rendered DOM.
+
+  When animations delay the removal of an embedded view, any new embedded views will be inserted after the embedded view that will be removed once the animation completes.
+  This difference only lasts while the animation is active, and might alter the visual appearance of the animation.
+  When the animation is finished, the resulting rendered DOM is identical to that rendered with View Engine.
+
+  One additional exception is the `<select>` element with `<option>` elements dynamically rendered using `NgForOf`. If a [`trackBy`](api/common/NgForOf#ngForTrackBy) function is not provided, the selected `<option>` will not be preserved when the iterable used by the `NgForOf` changes.
+  With View Engine, this programming error was obscured, and often not visible.
+  To avoid this problem, provide the `trackBy` function to correctly associate the model with the rendered DOM elements.
diff --git a/packages/core/src/change_detection/differs/iterable_differs.ts b/packages/core/src/change_detection/differs/iterable_differs.ts
index e05f94cd56..ec90548e33 100644
--- a/packages/core/src/change_detection/differs/iterable_differs.ts
+++ b/packages/core/src/change_detection/differs/iterable_differs.ts
@@ -126,6 +126,8 @@ export interface IterableChangeRecord<V> {
  * - preserve any DOM-specific UI state (like cursor position, focus, text selection) when the
  *   iterable is modified
  * - enable animation of item addition, removal, and iterable reordering
+ * - preserve the value of the `<select>` element when nested `<option>` elements are dynamically
+ *   populated using `NgForOf` and the bound iterable is updated
  *
  * A common use for custom `trackBy` functions is when the model that `NgForOf` iterates over
  * contains a property with a unique identifier. For example, given a model: