feat: add migration guide + update nav links

src/.vuepress/config.js

@@ -111,6 +111,7 @@ const sidebar = {
       collapsable: true,
       children: [
         'migration/introduction',
+        'migration/array-refs',
         'migration/async-components',
         'migration/attribute-coercion',
         'migration/custom-directives',
@@ -123,11 +124,15 @@ const sidebar = {
         'migration/global-api',
         'migration/global-api-treeshaking',
         'migration/inline-template-attribute',
+        'migration/key-attribute',
         'migration/keycode-modifiers',
+        'migration/props-default-this',
         'migration/render-function-api',
         'migration/slots-unification',
         'migration/transition',
-        'migration/v-model'
+        'migration/v-model',
+        'migration/v-if-v-for',
+        'migration/v-bind'
       ]
     },
     {
@@ -228,6 +233,10 @@ module.exports = {
             text: '教程',
             link: '/guide/introduction'
           },
+          {
+            text: 'v3 迁移指南',
+            link: '/guide/migration/introduction'
+          },
           {
             text: '风格指南',
             link: '/style-guide/'
@@ -273,7 +282,7 @@ module.exports = {
             text: '官方项目',
             items: [{
                 text: 'Vue Router',
-                link: 'https://router.vuejs.org/'
+                link: 'https://next.router.vuejs.org/'
               },
               {
                 text: 'Vuex',
@@ -285,7 +294,7 @@ module.exports = {
               },
               {
                 text: 'Vue Test Utils',
-                link: 'https://vue-test-utils.vuejs.org/'
+                link: 'https://vuejs.github.io/vue-test-utils-next-docs/guide/introduction.html'
               },
               {
                 text: 'Devtools',

src/api/application-api.md

@@ -35,7 +35,7 @@ app.component('my-component', {
   /* ... */
 })
 
-// 检索注册的组件（始终返回构造函数）
+// 检索注册的组件(始终返回构造函数)
 const MyComponent = app.component('my-component', {})
 ```
 
@@ -145,7 +145,7 @@ app.directive('focus', {
 上一个的虚拟 Node，仅在 `beforeUpdate` 和 `updated` 钩子中可用。
 
 :::tip Note
-除了 `el` 之外，你应该将这些参数视为只读，并且永远不要修改它们。如果你需要跨钩子共享信息，建议通过元素的[数据集] (https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) 进行共享。
+除了 `el` 之外，你应该将这些参数视为只读，并且永远不要修改它们。如果你需要跨钩子共享信息，建议通过元素的[数据集](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset)进行共享。
 :::
 
 - **参考**[自定义指令](../guide/custom-directive.html)

src/api/computed-watch-api.md

@@ -65,7 +65,7 @@ function watchEffect(
 ): StopHandle
 
 interface WatchEffectOptions {
-  flush?: 'pre' | 'post' | 'sync'
+  flush?: 'pre' | 'post' | 'sync'  // default: 'pre'
   onTrack?: (event: DebuggerEvent) => void
   onTrigger?: (event: DebuggerEvent) => void
 }

src/cookbook/editable-svg-icons.md

@@ -155,7 +155,7 @@ export default {
 
 ## 何时避免使用这种模式
 
-当你的站点中有大量以不同方式使用的图标时，这种类型的 SVG 图标系统非常有用。如果你在一个页面上多次重复使用同一个图标（例如：每行带有删除图标的巨型表格）更合理的做法是将所有的图标编译到一张雪碧图中，然后使用 `<use>` 标签来加载它们。
+当你的站点中有大量以不同方式使用的图标时，这种类型的 SVG 图标系统非常有用。如果你在一个页面上多次重复使用同一个图标 (例如：每行带有删除图标的巨型表格) 更合理的做法是将所有的图标编译到一张雪碧图中，然后使用 `<use>` 标签来加载它们。
 
 ## 其它替代方案
 

src/guide/component-basics.md

@@ -221,13 +221,13 @@ app.component('blog-post', {
 </button>
 ```
 
-当点击这个按钮时，我们需要告诉父级组件放大所有博文的文本。幸好 组件实例提供了一个自定义事件的系统来解决这个问题。父级组件可以像处理 native DOM 事件一样通过 `v-on` 或 `@` 监听子组件实例的任意事件：
+当点击这个按钮时，我们需要告诉父级组件放大所有博文的文本。幸好组件实例提供了一个自定义事件的系统来解决这个问题。父级组件可以像处理 native DOM 事件一样通过 `v-on` 或 `@` 监听子组件实例的任意事件：
 
 ```html
 <blog-post ... @enlarge-text="postFontSize += 0.1"></blog-post>
 ```
 
-同时子组件可以通过调用内建的 [**$emit** 方法](../api/instance-methods.html#emit) 并传入事件名称来触发一个事件：
+同时子组件可以通过调用内建的 [**$emit** 方法](../api/instance-methods.html#emit)并传入事件名称来触发一个事件：
 
 ```html
 <button @click="$emit('enlarge-text')">
@@ -311,7 +311,7 @@ methods: {
 ```
 
 ::: warning
-请注意，我们在这里使用的是 `model value`，因为我们使用的是DOM模板中的kebab-case。你可以在 [DOM Template Parsing Caveats](#dom-template-parsing-caveats) 部分找到关于kebab cased和camelCased属性的详细说明
+请注意，我们在这里使用的是 `model value`，因为我们使用的是 DOM 模板中的 kebab-case。你可以在 [DOM Template Parsing Caveats](#dom-template-parsing-caveats) 部分找到关于 kebab cased 和 camelCased 属性的详细说明
 :::
 
 为了让它正常工作，这个组件内的 `<input>` 必须：
@@ -343,7 +343,7 @@ app.component('custom-input', {
 
 在下面的示例中，我们使用计算属性重构 `<custom-input>` 组件。
 
-请记住，`get` 方法应返回 `modelValue` property，或用于绑定的任何 property，`set` 方法应为该 property 触发相应的 `$emit` 。
+请记住，`get` 方法应返回 `modelValue` property，或用于绑定的任何 property，`set` 方法应为该 property 触发相应的 `$emit`。
 
 ```js
 app.component('custom-input', {
@@ -363,7 +363,7 @@ app.component('custom-input', {
 })
 ```
 
-现在你只需要了解自定义组件事件，但一旦你读完本页并对其内容还觉得不错，我们建议你稍后再阅读有关 [自定义事件](component-custom-events.md)
+现在你只需要了解自定义组件事件，但一旦你读完本页并对其内容还觉得不错，我们建议你稍后再阅读有关[自定义事件](component-custom-events.md)
 
 ## 通过插槽分发内容
 
@@ -428,7 +428,7 @@ app.component('alert-box', {
 
 请留意，这个 attribute 可以用于常规 HTML 元素，但这些元素将被视为组件，这意味着所有的 attribute **都会作为 DOM attribute 被绑定**。对于像 `value` 这样的 property，若想让其如预期般工作，你需要使用 [.prop 修饰器](../api/directives.html#v-bind)。
 
-到目前为止，关于动态组件你需要了解的大概就这些了，如果你阅读完本页内容并掌握了它的内容，我们会推荐你再回来把 [动态 & 异步组件](./components-dynamic-async.html)读完。
+到目前为止，关于动态组件你需要了解的大概就这些了，如果你阅读完本页内容并掌握了它的内容，我们会推荐你再回来把[动态 & 异步组件](./components-dynamic-async.html)读完。
 
 ## 解析 DOM 模板时的注意事项
 
@@ -462,7 +462,7 @@ app.component('alert-box', {
 
 :::
 
-另外，HTML 属性名不区分大小写，因此浏览器将把所有大写字符解释为小写。这意味着当你在 DOM 模板中使用时，驼峰 prop 名称和 event 处理器参数需要使用它们的 kebab-cased（横线字符分隔）等效值：
+另外，HTML 属性名不区分大小写，因此浏览器将把所有大写字符解释为小写。这意味着当你在 DOM 模板中使用时，驼峰 prop 名称和 event 处理器参数需要使用它们的 kebab-cased (横线字符分隔) 等效值：
 
 
 ```js

src/guide/custom-directive.md

@@ -125,7 +125,7 @@ app.directive('pin', {
 app.mount('#dynamic-arguments-example')
 ```
 
-结果:
+结果：
 
 <p class="codepen" data-height="300" data-theme-id="39028" data-default-tab="result" data-user="Vue" data-slug-hash="YzXgGmv" data-editable="true" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="Custom directives: dynamic arguments">
   <span>See the Pen <a href="https://codepen.io/team/Vue/pen/YzXgGmv">
@@ -171,7 +171,7 @@ app.directive('pin', {
 })
 ```
 
-结果:
+结果：
 
 <p class="codepen" data-height="300" data-theme-id="39028" data-default-tab="result" data-user="Vue" data-slug-hash="rNOaZpj" data-editable="true" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="Custom directives: dynamic arguments + dynamic binding">
   <span>See the Pen <a href="https://codepen.io/team/Vue/pen/rNOaZpj">
@@ -228,7 +228,7 @@ return withDirectives(h('div'), [[vDemo, test]])
 
 其中 `vDemo` 是用户编写的指令对象，其中包含 `mounted` 和 `updated` 等钩子。
 
-`withDirectives` 返回一个克隆的 VNode，其中用户钩子被包装并作为 VNode 生命周期钩子注入（请参见[渲染函数](ender-function.html)）更多详情）：
+`withDirectives` 返回一个克隆的 VNode，其中用户钩子被包装并作为 VNode 生命周期钩子注入 (请参见[渲染函数](ender-function.html)更多详情)：
 
 ```js
 {

src/guide/installation.md

@@ -2,15 +2,13 @@
 
 ## 发布版本说明
 
-最新 beta 版本：![beta](https://img.shields.io/npm/v/vue/next.svg)
+最新版本：![npm](https://img.shields.io/npm/v/vue/next.svg)
 
-每个版本的详细发行说明可在 [GitHub](https://github.com/vuejs/vue-next/releases) 上找到。
+每个版本的详细发行说明可在 [GitHub](https://github.com/vuejs/vue-next/blob/master/CHANGELOG.md) 上找到。
 
 ## Vue Devtools
 
-> 当前是 Beta 阶段
-
-> Vue Devtools 需要 Vue 3 版本不得低于 `vue@^3.0.0-rc.1`
+> 当前是 Beta 版 —— Vuex 和 Router 的集成仍然是 WIP 
 
 在使用 Vue 时，我们推荐在你的浏览器上安装 [Vue Devtools](https://github.com/vuejs/vue-devtools#vue-devtools)，它允许你在一个更友好的界面中审查和调试 Vue 应用。
 

src/guide/introduction.md

@@ -1,5 +1,9 @@
 # 介绍
 
+::: tip 提示
+已经了解 Vue 2，只想了解 Vue 3 的新功能可以参阅[迁移指南](/guide/migration/introduction.html)!
+:::
+
 ## Vue.js 是什么
 
 Vue (读音 /vjuː/，类似于 **view**) 是一套用于构建用户界面的**渐进式框架**。与其它大型框架不同的是，Vue 被设计为可以自底向上逐层应用。Vue 的核心库只关注视图层，不仅易于上手，还便于与第三方库或既有项目整合。另一方面，当与[现代化的工具链](../guide/single-file-component.html)以及各种[支持类库](https://github.com/vuejs/awesome-vue#components--libraries)结合使用时，Vue 也完全能够为复杂的单页应用提供驱动。

src/guide/migration/array-refs.md

@@ -0,0 +1,69 @@
+---
+title: v-for Array Refs
+badges:
+- breaking
+---
+
+# {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
+
+In Vue 2, using the `ref` attribute inside `v-for` will populate the corresponding `$refs` property with an array of refs. This behavior becomes ambiguous and inefficient when there are nested `v-for`s present.
+
+In Vue 3, such usage will no longer automatically create an array in `$refs`. To retrieve multiple refs from a single binding, bind `ref` to a function which provides more flexibility (this is a new feature):
+
+```html
+<div v-for="item in list" :ref="setItemRef"></div>
+```
+
+With Options API:
+
+```js
+export default {
+  data() {
+    return {
+      itemRefs: []
+    }
+  },
+  methods: {
+    setItemRef(el) {
+      this.itemRefs.push(el)
+    }
+  },
+  beforeUpdate() {
+    this.itemRefs = []
+  },
+  updated() {
+    console.log(this.itemRefs)
+  }
+}
+```
+
+With Composition API:
+
+```js
+import { ref, onBeforeUpdate, onUpdated } from 'vue'
+
+export default {
+  setup() {
+    let itemRefs = []
+    const setItemRef = el => {
+      itemRefs.push(el)
+    }
+    onBeforeUpdate(() => {
+      itemRefs = []
+    })
+    onUpdated(() => {
+      console.log(itemRefs)
+    })
+    return {
+      itemRefs,
+      setItemRef
+    }
+  }
+}
+```
+
+Note that:
+
+- `itemRefs` doesn't have to be an array: it can also be an object where the refs are set by their iteration keys.
+
+- This also allows `itemRefs` to be made reactive and watched, if needed.

src/guide/migration/custom-elements-interop.md

@@ -3,7 +3,7 @@ badges:
   - breaking
 ---
 
-# 自定义元素交互变更 <MigrationBadges :badges="$frontmatter.badges" />
+# 自定义元素交互 <MigrationBadges :badges="$frontmatter.badges" />
 
 ## 概览
 

src/guide/migration/data-option.md

@@ -4,15 +4,17 @@ badges:
   - breaking
 ---
 
-#{{ $frontmatter.title}} <MigrationBadges :badges="$frontmatter.badges" />
+# {{ $frontmatter.title}} <MigrationBadges :badges="$frontmatter.badges" />
 
 ## 概览
 
-- **BREAKING**：`data` 组件选项声明不再接收纯 JavaScript `object`，而需要 `function` 声明
+- **breaking**：`data` 组件选项声明不再接收纯 JavaScript `object`，而需要 `function` 声明。
+
+当合并来自 mixin 或 extend 的多个 `data` 返回值时，现在是浅层次合并的而不是深层次合并的(只合并根级属性)。
 
 ## 2.x Syntax
 
-在 2.x 中，开发者可以定义 `data` 选项是 `object` 或者是 `function`
+在 2.x 中，开发者可以定义 `data` 选项是 `object` 或者是 `function`。
 
 例如：
 
@@ -60,9 +62,59 @@ badges:
 </script>
 ```
 
+## Mixin 合并行为变更
+
+此外，当来自组件的 `data()` 及其 mixin 或 extends 基类被合并时，现在将*浅层次*执行合并：
+
+```js
+const Mixin = {
+  data() {
+    return {
+      user: {
+        name: 'Jack',
+        id: 1
+      }
+    }
+  }
+}
+const CompA = {
+  mixins: [Mixin],
+  data() {
+    return {
+      user: {
+        id: 2
+      }
+    }
+  }
+}
+```
+
+在 Vue 2.x中，生成的 `$data` 是：
+
+```json
+{
+  user: {
+    id: 2,
+    name: 'Jack'
+  }
+}
+```
+
+在 3.0 中，其结果将会是：
+
+```json
+{
+  user: {
+    id: 2
+  }
+}
+```
+
 ## 迁移策略
 
 对于依赖对象声明的用户，我们建议：
 
 - 将共享数据提取到外部对象并将其用作 `data` 中的 property
-- 重写对共享数据的引用以指向新的共享对象
+- 重写对共享数据的引用以指向新的共享对象
+
+对于依赖 mixin 的深度合并行为的用户，我们建议重构代码以完全避免这种依赖，因为 mixin 的深度合并非常隐式，这让代码逻辑更难理解和调试。