From 19ef22bd82e7994d5a0a3a689ae6e7c75170dbc3 Mon Sep 17 00:00:00 2001
From: "22969541+Aurelius333@users.noreply.github.com"
 <22969541+Aurelius333@users.noreply.github.com>
Date: Tue, 15 Sep 2020 23:57:19 -0400
Subject: [PATCH 1/2] feat: add migration guide section about "key" attribute
 changes Fix #379

---
 src/.vuepress/config.js              | 86 +++++++++++++++-----------
 src/guide/migration/introduction.md  |  1 +
 src/guide/migration/key-attribute.md | 91 ++++++++++++++++++++++++++++
 3 files changed, 144 insertions(+), 34 deletions(-)
 create mode 100644 src/guide/migration/key-attribute.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index aff8c46424..72f98ba57c 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -1,10 +1,13 @@
 const sidebar = {
-  cookbook: [{
-    title: 'Cookbook',
-    collapsable: false,
-    children: ['/cookbook/', '/cookbook/editable-svg-icons']
-  }],
-  guide: [{
+  cookbook: [
+    {
+      title: 'Cookbook',
+      collapsable: false,
+      children: ['/cookbook/', '/cookbook/editable-svg-icons']
+    }
+  ],
+  guide: [
+    {
       title: 'Essentials',
       collapsable: false,
       children: [
@@ -60,7 +63,8 @@ const sidebar = {
     {
       title: 'Advanced Guides',
       collapsable: false,
-      children: [{
+      children: [
+        {
           title: 'Reactivity',
           children: [
             '/guide/reactivity',
@@ -123,6 +127,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',
@@ -172,21 +177,23 @@ const sidebar = {
     },
     '/api/composition-api'
   ],
-  examples: [{
-    title: 'Examples',
-    collapsable: false,
-    children: [
-      '/examples/markdown',
-      '/examples/commits',
-      '/examples/grid-component',
-      '/examples/tree-view',
-      '/examples/svg',
-      '/examples/modal',
-      '/examples/elastic-header',
-      '/examples/select2',
-      '/examples/todomvc'
-    ]
-  }]
+  examples: [
+    {
+      title: 'Examples',
+      collapsable: false,
+      children: [
+        '/examples/markdown',
+        '/examples/commits',
+        '/examples/grid-component',
+        '/examples/tree-view',
+        '/examples/svg',
+        '/examples/modal',
+        '/examples/elastic-header',
+        '/examples/select2',
+        '/examples/todomvc'
+      ]
+    }
+  ]
 }
 
 module.exports = {
@@ -196,21 +203,26 @@ module.exports = {
     [
       'link',
       {
-        href: 'https://fonts.googleapis.com/css?family=Inter:300,400,500,600|Open+Sans:400,600;display=swap',
+        href:
+          'https://fonts.googleapis.com/css?family=Inter:300,400,500,600|Open+Sans:400,600;display=swap',
         rel: 'stylesheet'
       }
     ],
     [
       'link',
       {
-        href: 'https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css',
+        href:
+          'https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css',
         rel: 'stylesheet'
       }
     ],
-    ['link', {
-      rel: 'icon',
-      href: '/logo.png'
-    }],
+    [
+      'link',
+      {
+        rel: 'icon',
+        href: '/logo.png'
+      }
+    ],
     [
       'script',
       {
@@ -227,10 +239,12 @@ module.exports = {
   ],
   themeConfig: {
     logo: '/logo.png',
-    nav: [{
+    nav: [
+      {
         text: 'Docs',
         ariaLabel: 'Documentation Menu',
-        items: [{
+        items: [
+          {
             text: 'Guide',
             link: '/guide/introduction'
           },
@@ -254,10 +268,12 @@ module.exports = {
       },
       {
         text: 'Ecosystem',
-        items: [{
+        items: [
+          {
             text: 'Community',
             ariaLabel: 'Community Menu',
-            items: [{
+            items: [
+              {
                 text: 'Team',
                 link: '/community/team/'
               },
@@ -277,7 +293,8 @@ module.exports = {
           },
           {
             text: 'Official Projects',
-            items: [{
+            items: [
+              {
                 text: 'Vue Router',
                 link: 'https://router.vuejs.org/'
               },
@@ -308,7 +325,8 @@ module.exports = {
       {
         text: 'Support Vue',
         link: '/support-vuejs/',
-        items: [{
+        items: [
+          {
             text: 'One-time Donations',
             link: '/support-vuejs/#one-time-donations'
           },
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>
+```

From 655ab2a7055f300a734a2c3d5f1e0c664de9157b Mon Sep 17 00:00:00 2001
From: "22969541+Aurelius333@users.noreply.github.com"
 <22969541+Aurelius333@users.noreply.github.com>
Date: Wed, 16 Sep 2020 00:01:45 -0400
Subject: [PATCH 2/2] undo formatting changes in config.js

---
 src/.vuepress/config.js | 85 +++++++++++++++++------------------------
 1 file changed, 34 insertions(+), 51 deletions(-)

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 72f98ba57c..06d47555dc 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -1,13 +1,10 @@
 const sidebar = {
-  cookbook: [
-    {
-      title: 'Cookbook',
-      collapsable: false,
-      children: ['/cookbook/', '/cookbook/editable-svg-icons']
-    }
-  ],
-  guide: [
-    {
+  cookbook: [{
+    title: 'Cookbook',
+    collapsable: false,
+    children: ['/cookbook/', '/cookbook/editable-svg-icons']
+  }],
+  guide: [{
       title: 'Essentials',
       collapsable: false,
       children: [
@@ -63,8 +60,7 @@ const sidebar = {
     {
       title: 'Advanced Guides',
       collapsable: false,
-      children: [
-        {
+      children: [{
           title: 'Reactivity',
           children: [
             '/guide/reactivity',
@@ -177,23 +173,21 @@ const sidebar = {
     },
     '/api/composition-api'
   ],
-  examples: [
-    {
-      title: 'Examples',
-      collapsable: false,
-      children: [
-        '/examples/markdown',
-        '/examples/commits',
-        '/examples/grid-component',
-        '/examples/tree-view',
-        '/examples/svg',
-        '/examples/modal',
-        '/examples/elastic-header',
-        '/examples/select2',
-        '/examples/todomvc'
-      ]
-    }
-  ]
+  examples: [{
+    title: 'Examples',
+    collapsable: false,
+    children: [
+      '/examples/markdown',
+      '/examples/commits',
+      '/examples/grid-component',
+      '/examples/tree-view',
+      '/examples/svg',
+      '/examples/modal',
+      '/examples/elastic-header',
+      '/examples/select2',
+      '/examples/todomvc'
+    ]
+  }]
 }
 
 module.exports = {
@@ -203,26 +197,21 @@ module.exports = {
     [
       'link',
       {
-        href:
-          'https://fonts.googleapis.com/css?family=Inter:300,400,500,600|Open+Sans:400,600;display=swap',
+        href: 'https://fonts.googleapis.com/css?family=Inter:300,400,500,600|Open+Sans:400,600;display=swap',
         rel: 'stylesheet'
       }
     ],
     [
       'link',
       {
-        href:
-          'https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css',
+        href: 'https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css',
         rel: 'stylesheet'
       }
     ],
-    [
-      'link',
-      {
-        rel: 'icon',
-        href: '/logo.png'
-      }
-    ],
+    ['link', {
+      rel: 'icon',
+      href: '/logo.png'
+    }],
     [
       'script',
       {
@@ -239,12 +228,10 @@ module.exports = {
   ],
   themeConfig: {
     logo: '/logo.png',
-    nav: [
-      {
+    nav: [{
         text: 'Docs',
         ariaLabel: 'Documentation Menu',
-        items: [
-          {
+        items: [{
             text: 'Guide',
             link: '/guide/introduction'
           },
@@ -268,12 +255,10 @@ module.exports = {
       },
       {
         text: 'Ecosystem',
-        items: [
-          {
+        items: [{
             text: 'Community',
             ariaLabel: 'Community Menu',
-            items: [
-              {
+            items: [{
                 text: 'Team',
                 link: '/community/team/'
               },
@@ -293,8 +278,7 @@ module.exports = {
           },
           {
             text: 'Official Projects',
-            items: [
-              {
+            items: [{
                 text: 'Vue Router',
                 link: 'https://router.vuejs.org/'
               },
@@ -325,8 +309,7 @@ module.exports = {
       {
         text: 'Support Vue',
         link: '/support-vuejs/',
-        items: [
-          {
+        items: [{
             text: 'One-time Donations',
             link: '/support-vuejs/#one-time-donations'
           },