docs: update menu and migration guides

Author: bencodezen

src/.vuepress/config.js

@@ -107,7 +107,7 @@ const sidebar = {
       ]
     },
     {
-      title: 'Migration from Vue 2',
+      title: 'Migration Guide',
       collapsable: true,
       children: [
         'migration/introduction',
@@ -240,7 +240,7 @@ module.exports = {
             link: '/guide/introduction'
           },
           {
-            text: 'v3 Migration Guide',
+            text: 'Migration Guide',
             link: '/guide/migration/introduction'
           },
           {

src/guide/migration/introduction.md

@@ -47,7 +47,7 @@ Some of the new features to keep an eye on in Vue 3 include:
 
 ## Breaking Changes
 
-::: tip NOTE
+::: info INFO
 We are still working on a dedicated Migration Build of Vue 3 with Vue 2 compatible behavior and runtime warnings of incompatible usage. If you are planning to migrate a non-trivial Vue 2 app, we strongly recommend waiting for the Migration Build for a smoother experience.
 :::
 
@@ -84,15 +84,15 @@ The following consists a list of breaking changes from 2.x:
 
 ### Other Minor Changes
 
-- The ~~`destroyed`~~ lifecycle option has been renamed to `unmounted`
-- The ~~`beforeDestroy`~~ lifecycle option has been renamed to `beforeUnmount`
+- The `destroyed` lifecycle option has been renamed to `unmounted`
+- The `beforeDestroy` lifecycle option has been renamed to `beforeUnmount`
 - [Props `default` factory function no longer has access to `this` context](/guide/migration/props-default-this.html)
 - [Custom directive API changed to align with component lifecycle](/guide/migration/custom-directives.html)
 - [The `data` option should always be declared as a function](/guide/migration/data-option.html)
 - [The `data` option from mixins is now merged shallowly](/guide/migration/data-option.html#mixin-merge-behavior-change)
 - [Attributes coercion strategy changed](/guide/migration/attribute-coercion.html)
 - [Some transition classes got a rename](/guide/migration/transition.html)
-- When using [the `watch` option](/api/options-data.html#watch) to watch an array, the callback will only trigger when the array is replaced, and no longer trigger on array mutation. To trigger on mutation, the `deep` option must be specified. This is a side effect of more precise dependency tracking in Vue 3.
+- [When watching an array, the callback will only trigger when the array is replaced. If you need to to trigger on mutation, the `deep` option must be specified.](/guide/migration/watch.html)
 - `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
 - 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 - this means the container itself is no longer considered part of the template.
 

src/guide/migration/v-bind.md

@@ -6,18 +6,41 @@ badges:
 
 # {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
 
-In Vue 2, individual bindings always overwrites `v-bind="object"` bindings when used on the same element. In Vue 3, the order of the bindings will affect the rendering result:
+## Overview
+
+- **BREAKING**: Order of bindings for v-bind will affect the rendering result.
+
+## Introduction
+
+When dynamically binding attributes on an element, a common scenario involves using both the `v-bind="object"` syntax as well as individual properties in the same element. However, this raises questions as far as the priority of merging.
+
+## 2.x Syntax
+
+In 2.x, if an element has both `v-bind="object"` and an identical individual property defined, the individual property would always overwrite bindings in the `object`. 
 
 ```html
 <!-- template -->
-<div id="foo" v-bind="{ id: 'bar' }"></div>
+<div id="red" v-bind="{ id: 'blue' }"></div>
 <!-- result -->
-<div id="bar"></div>
+<div id="red"></div>
+```
+
+## 3.x Syntax
+
+In 3x, if an element has both `v-bind="object"` and an identical individual property defined, the order of how the bindings are declared determines how they are merged. In other words, rather than assuming developers want the individual property to always override what is defined in the `object`, developers now have more control over the desired merging behavior.
+
+```html
+<!-- template -->
+<div id="red" v-bind="{ id: 'blue' }"></div>
+<!-- result -->
+<div id="blue"></div>
 
 <!-- template -->
-<div v-bind="{ id: 'bar' }" id="foo"></div>
+<div v-bind="{ id: 'blue' }" id="red"></div>
 <!-- result -->
-<div id="foo"></div>
+<div id="red"></div>
 ```
 
-This is a minor breaking change, but gives the user more control over the desired merging behavior.
+## Migration Strategy
+
+If you are relying on this override functionality for `v-bind`, we currently recommending ensuring that your 

src/guide/migration/v-if-v-for.md

@@ -6,12 +6,24 @@ badges:
 
 # {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
 
-The precedence of `v-if` and `v-for` have been flipped when using both on the same element. In Vue 3, `v-if` will always have the higher precedence.
+## Overview
 
-It is recommended to avoid using both on the same element due to the syntax ambiguity. Use separate `<template v-if|for>` containers when both are needed at the same time:
+- **BREAKING**: If used on the same element, `v-if` will have higher precedence than `v-for`
 
-```html
-<template v-for="item in items" :key="item.id">
-  <div v-if="item.visible">{{ item.text }}</div>
-</template>
-```
+## Introduction
+
+Two of the most commonly used directives in Vue.js are `v-if` and `v-for`. So it's no surprise that there comes a time when developers want to use both together. While this is not a recommended practice, there may be times when this is necessary, so we wanted to provide guidance for how it works.
+
+## 2.x Syntax
+
+In 2.x, when using `v-if` and `v-for` on the same element, `v-for` would take precedence.
+
+## 3.x Syntax
+
+In 3.x, `v-if` will always have the higher precedence than `v-for`.
+
+## Migration Strategy
+
+It is recommended to avoid using both on the same element due to the syntax ambiguity.
+
+Rather than managing this at the template level, one method for accomplishing this is to create a computed property that filters out a list for the visible elements.

src/guide/migration/watch.md

@@ -0,0 +1,30 @@
+---
+title: Watch on Arrays
+badges:
+  - breaking
+---
+
+# {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
+
+## Overview
+
+- **BREAKING**: When watching an array, the callback will only trigger when the array is replaced. If you need to to trigger on mutation, the `deep` option must be specified.
+
+## 3.x Syntax
+
+When using [the `watch` option](/api/options-data.html#watch) to watch an array, the callback will only trigger when the array is replaced. In other words, the watch callback will no longer be triggered on array mutation. To trigger on mutation, the `deep` option must be specified.
+
+```js
+watch: {
+  bookList: {
+    handler(val, oldVal) {
+      console.log('book list changed')
+    },
+    deep: true
+  },
+}
+```
+
+## Migration Strategy
+
+If you rely on watching array mutations, add the `deep` property to ensure that your callback is triggered correctly.