From 31c7d047909dd859545dd18cc98a9ee855d1f737 Mon Sep 17 00:00:00 2001
From: Aurelius333 <22969541+Aurelius333@users.noreply.github.com>
Date: Wed, 16 Sep 2020 02:17:05 -0400
Subject: [PATCH] Migration guide section on key attribute changes (#481)

* feat: add migration guide section about "key" attribute changes
Fix #379

* undo formatting changes in config.js
---
 src/.vuepress/config.js              |  1 +
 src/guide/migration/introduction.md  |  1 +
 src/guide/migration/key-attribute.md | 91 ++++++++++++++++++++++++++++
 3 files changed, 93 insertions(+)
 create mode 100644 src/guide/migration/key-attribute.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index aff8c46424..06d47555dc 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -123,6 +123,7 @@ const sidebar = {
         'migration/global-api',
         'migration/global-api-treeshaking',
         'migration/inline-template-attribute',
+        'migration/key-attribute',
         'migration/keycode-modifiers',
         'migration/render-function-api',
         'migration/slots-unification',
diff --git a/src/guide/migration/introduction.md b/src/guide/migration/introduction.md
index f2b50b9e43..022434b218 100644
--- a/src/guide/migration/introduction.md
+++ b/src/guide/migration/introduction.md
@@ -42,6 +42,7 @@ The following consists a list of breaking changes from 2.x:
 - [Custom directive API changed to align with component lifecycle](/guide/migration/custom-directives.html)
 - [Some transition classes got a rename](/guide/migration/transition.md)
 - [Component watch option](/api/options-data.html#watch) and [instance method `$watch`](/api/instance-methods.html#watch) no longer supports dot-delimited string paths, use a computed function as the parameter instead
+- [Changes in `key` attribute usage with `v-if` and `<template v-for>`](/guide/migration/key-attribute.md)
 - In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead.
 
 ### Removed
diff --git a/src/guide/migration/key-attribute.md b/src/guide/migration/key-attribute.md
new file mode 100644
index 0000000000..562e473c1e
--- /dev/null
+++ b/src/guide/migration/key-attribute.md
@@ -0,0 +1,91 @@
+---
+badges:
+  - breaking
+---
+
+# `key` attribute <MigrationBadges :badges="$frontmatter.badges" />
+
+## Overview
+
+- **NEW:** `key`s are no longer necessary on `v-if`/`v-else`/`v-else-if` branches, since Vue now automatically generates unique `key`s.
+  - **BREAKING:** If you manually provide `key`s, then each branch must use a unique `key`.
+- **BREAKING:** `<template v-for>` `key` should be placed on the `<template>` tag (rather than on its children).
+
+## Background
+
+The `key` special attribute is used as a hint for Vue's virtual DOM algorithm to keep track of a node's identity. That way, Vue knows when it can reuse and patch existing nodes and when it needs to reorder or recreate them. For more information, see the following sections:
+
+- [List Rendering: Maintaining State](/guide/list.html#maintaining-state)
+- [API Reference: `key` Special Attribute](/api/special-attributes.html#key)
+
+## On conditional branches
+
+In Vue 2.x, it was recommended to use `key`s on `v-if`/`v-else`/`v-else-if` branches.
+
+```html
+<!-- Vue 2.x -->
+<div v-if="condition" key="yes">Yes</div>
+<div v-else key="no">No</div>
+```
+
+The example above still works in Vue 3.x. However, we no longer recommend using the `key` attribute on `v-if`/`v-else`/`v-else-if` branches, since unique `key`s are now automatically generated on conditional branches if you don't provide them.
+
+```html
+<!-- Vue 3.x -->
+<div v-if="condition">Yes</div>
+<div v-else>No</div>
+```
+
+The breaking change is that if you manually provide `key`s, each branch must use a unique `key`. In most cases, you can remove these `key`s.
+
+```html
+<!-- Vue 2.x -->
+<div v-if="condition" key="a">Yes</div>
+<div v-else key="a">No</div>
+
+<!-- Vue 3.x (recommended solution: remove keys) -->
+<div v-if="condition">Yes</div>
+<div v-else>No</div>
+
+<!-- Vue 3.x (alternate solution: make sure the keys are always unique) -->
+<div v-if="condition" key="a">Yes</div>
+<div v-else key="b">No</div>
+```
+
+## With `<template v-for>`
+
+In Vue 2.x, a `<template>` tag could not have a `key`. Instead, you could place the `key`s on each of its children.
+
+```html
+<!-- Vue 2.x -->
+<template v-for="item in list">
+  <div :key="item.id">...</div>
+  <span :key="item.id">...</span>
+</template>
+```
+
+In Vue 3.x, the `key` should be placed on the `<template>` tag instead.
+
+```html
+<!-- Vue 3.x -->
+<template v-for="item in list" :key="item.id">
+  <div>...</div>
+  <span>...</span>
+</template>
+```
+
+Similarly, when using `<template v-for>` with a child that uses `v-if`, the `key` should be moved up to the `<template>` tag.
+
+```html
+<!-- Vue 2.x -->
+<template v-for="item in list">
+  <div v-if="item.isVisible" :key="item.id">...</div>
+  <span v-else :key="item.id">...</span>
+</template>
+
+<!-- Vue 3.x -->
+<template v-for="item in list" :key="item.id">
+  <div v-if="item.isVisible">...</div>
+  <span v-else>...</span>
+</template>
+```