Migration introduction improvement (#186)

NataliaTepluhina · web-flow · commit 5f669247f4aa · 2020-07-15T16:14:32.000+03:00
* feat: added removed and breaking features

* fix: removed outdated info from installation

* fix: added custom components interop
diff --git a/src/guide/installation.md b/src/guide/installation.md
@@ -2,7 +2,7 @@
 
 ## Release Notes
 
-Latest beta version: 3.0.0-beta.14
+Latest beta version: 3.0.0-beta.121
 
 Detailed release notes for each version are available on [GitHub](https://github.com/vuejs/vue-next/releases).
 
@@ -22,18 +22,13 @@ For prototyping or learning purposes, you can use the latest version with:
 
 For production, we recommend linking to a specific version number and build to avoid unexpected breakage from newer versions.
 
-Make sure to read about [the different builds of Vue](#explanation-of-different-builds) and use the **production
-version** in your published site, replacing `vue.js` with `vue.min.js`. This is a smaller build optimized for speed instead of development experience.
-
 ## NPM
 
-> Currently not available for Vue 3
-
 NPM is the recommended installation method when building large scale applications with Vue. It pairs nicely with module bundlers such as [Webpack](https://webpack.js.org/) or [Browserify](http://browserify.org/). Vue also provides accompanying tools for authoring [Single File Components](../guide/single-file-component.html).
 
 ```bash
 # latest stable
-$ npm install vue
+$ npm install vue@next
 ```
 
 ## CLI
@@ -45,201 +40,3 @@ The CLI assumes prior knowledge of Node.js and the associated build tools. If yo
 :::
 
 For beta, Vue CLI now has experimental support via [vue-cli-plugin-vue-next](https://github.com/vuejs/vue-cli-plugin-vue-next).
-
-## Explanation of Different Builds
-
-In the [`dist/` directory of the NPM package](TODO) you will find many different builds of Vue.js. Here's an overview of the difference between them:
-
-|                               | UMD                | CommonJS              | ES Module (for bundlers) | ES Module (for browsers) |
-| ----------------------------- | ------------------ | --------------------- | ------------------------ | ------------------------ |
-| **Full**                      | vue.js             | vue.common.js         | vue.esm.js               | vue.esm.browser.js       |
-| **Runtime-only**              | vue.runtime.js     | vue.runtime.common.js | vue.runtime.esm.js       | -                        |
-| **Full (production)**         | vue.min.js         | -                     | -                        | vue.esm.browser.min.js   |
-| **Runtime-only (production)** | vue.runtime.min.js | -                     | -                        | -                        |
-
-### Terms
-
-- **Full**: builds that contain both the compiler and the runtime.
-
-- **Compiler**: code that is responsible for compiling template strings into JavaScript render functions.
-
-- **Runtime**: code that is responsible for creating Vue instances, rendering and patching virtual DOM, etc. Basically everything minus the compiler.
-
-- **[UMD](https://github.com/umdjs/umd)**: UMD builds can be used directly in the browser via a `<script>` tag. The default file from jsDelivr CDN at [https://cdn.jsdelivr.net/npm/vue](https://cdn.jsdelivr.net/npm/vue) is the Runtime + Compiler UMD build (`vue.js`).
-
-- **[CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1)**: CommonJS builds are intended for use with older bundlers like [browserify](http://browserify.org/) or [webpack 1](https://webpack.github.io). The default file for these bundlers (`pkg.main`) is the Runtime only CommonJS build (`vue.runtime.common.js`).
-
-- **[ES Module](http://exploringjs.com/es6/ch_modules.html)**: starting in 2.6 Vue provides two ES Modules (ESM) builds:
-
-  - ESM for bundlers: intended for use with modern bundlers like [webpack 2](https://webpack.js.org) or [Rollup](https://rollupjs.org/). ESM format is designed to be statically analyzable so the bundlers can take advantage of that to perform "tree-shaking" and eliminate unused code from your final bundle. The default file for these bundlers (`pkg.module`) is the Runtime only ES Module build (`vue.runtime.esm.js`).
-
-  - ESM for browsers (2.6+ only): intended for direct imports in modern browsers via `<script type="module">`.
-
-### Runtime + Compiler vs. Runtime-only
-
-If you need to compile templates on the client (e.g. passing a string to the `template` option, or mounting to an element using its in-DOM HTML as the template), you will need the compiler and thus the full build:
-
-```js
-// this requires the compiler
-Vue.createApp({
-  template: '<div>{{ hi }}</div>'
-})
-
-// this does not
-Vue.createApp({
-  render() {
-    return Vue.h('div', this.hi)
-  }
-})
-```
-
-When using `vue-loader` or `vueify`, templates inside `*.vue` files are pre-compiled into JavaScript at build time. You don't really need the compiler in the final bundle, and can therefore use the runtime-only build.
-
-Since the runtime-only builds are roughly 30% lighter-weight than their full-build counterparts, you should use it whenever you can. If you still wish to use the full build instead, you need to configure an alias in your bundler:
-
-#### Webpack
-
-```js
-module.exports = {
-  // ...
-  resolve: {
-    alias: {
-      vue$: 'vue/dist/vue.esm.js' // 'vue/dist/vue.common.js' for webpack 1
-    }
-  }
-}
-```
-
-#### Rollup
-
-```js
-const alias = require('rollup-plugin-alias')
-
-rollup({
-  // ...
-  plugins: [
-    alias({
-      vue: require.resolve('vue/dist/vue.esm.js')
-    })
-  ]
-})
-```
-
-#### Browserify
-
-Add to your project's `package.json`:
-
-```js
-{
-  // ...
-  "browser": {
-    "vue": "vue/dist/vue.common.js"
-  }
-}
-```
-
-#### Parcel
-
-Add to your project's `package.json`:
-
-```js
-{
-  // ...
-  "alias": {
-    "vue" : "./node_modules/vue/dist/vue.common.js"
-  }
-}
-```
-
-### Development vs. Production Mode
-
-Development/production modes are hard-coded for the UMD builds: the un-minified files are for development, and the minified files are for production.
-
-CommonJS and ES Module builds are intended for bundlers, therefore we don't provide minified versions for them. You will be responsible for minifying the final bundle yourself.
-
-CommonJS and ES Module builds also preserve raw checks for `process.env.NODE_ENV` to determine the mode they should run in. You should use appropriate bundler configurations to replace these environment variables in order to control which mode Vue will run in. Replacing `process.env.NODE_ENV` with string literals also allows minifiers like UglifyJS to completely drop the development-only code blocks, reducing final file size.
-
-#### Webpack
-
-In Webpack 4+, you can use the `mode` option:
-
-```js
-module.exports = {
-  mode: 'production'
-}
-```
-
-But in Webpack 3 and earlier, you'll need to use [DefinePlugin](https://webpack.js.org/plugins/define-plugin/):
-
-```js
-var webpack = require('webpack')
-
-module.exports = {
-  // ...
-  plugins: [
-    // ...
-    new webpack.DefinePlugin({
-      'process.env': {
-        NODE_ENV: JSON.stringify('production')
-      }
-    })
-  ]
-}
-```
-
-#### Rollup
-
-Use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace):
-
-```js
-const replace = require('rollup-plugin-replace')
-
-rollup({
-  // ...
-  plugins: [
-    replace({
-      'process.env.NODE_ENV': JSON.stringify('production')
-    })
-  ]
-}).then(...)
-```
-
-#### Browserify
-
-Apply a global [envify](https://github.com/hughsk/envify) transform to your bundle.
-
-```bash
-NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
-```
-
-Also see [Production Deployment Tips](deployment.html).
-
-### CSP environments
-
-Some environments, such as Google Chrome Apps, enforce Content Security Policy (CSP), which prohibits the use of `new Function()` for evaluating expressions. The full build depends on this feature to compile templates, so is unusable in these environments.
-
-On the other hand, the runtime-only build is fully CSP-compliant. When using the runtime-only build with [Webpack + vue-loader](https://github.com/vuejs-templates/webpack-simple) or [Browserify + vueify](https://github.com/vuejs-templates/browserify-simple), your templates will be precompiled into `render` functions which work perfectly in CSP environments.
-
-## Dev Build
-
-**Important**: the built files in GitHub's `/dist` folder are only checked-in during releases. To use Vue from the latest source code on GitHub, you will have to build it yourself!
-
-```bash
-git clone https://github.com/vuejs/vue.git node_modules/vue
-cd node_modules/vue
-npm install
-npm run build
-```
-
-## Bower
-
-Only UMD builds are available from Bower.
-
-```bash
-# latest stable
-$ bower install vue
-```
-
-## AMD Module Loaders
-
-All UMD builds can be used directly as an AMD module.
diff --git a/src/guide/migration/introduction.md b/src/guide/migration/introduction.md
@@ -4,9 +4,7 @@
 
 We're glad you asked! The answer is no. We've gone to great lengths to ensure most of the API is the same and the core concepts haven't changed. It's long because we like to offer very detailed explanations and include a lot of examples. Rest assured, **this is not something you have to read from top to bottom!**
 
-[//]: # 'TODO: update composition API with a link'
-
-Possibly the biggest change is our new Composition API, which is entirely additive- the previous Options API will continue to be supported, as the Composition API is an advanced feature.
+Possibly the biggest change is our new [Composition API](/guide/composition-api-introduction.html), which is entirely additive- the previous Options API will continue to be supported, as the Composition API is an advanced feature.
 
 ## Overview
 
@@ -15,22 +13,35 @@ Possibly the biggest change is our new Composition API, which is entirely additi
 Some of the new features to keep an eye on in Vue 3 include:
 
 - [Composition API](/guide/composition-api-introduction.html)
-- [Teleport](/guide/teleport)
-- [Fragments](/guide/migration/fragments)
+- [Teleport](/guide/teleport.html)
+- [Fragments](/guide/migration/fragments.html)
 - [Emits Component Option](/guide/component-custom-events.html)
 - `createRenderer` API from `@vue/runtime-core` to create custom renderers
 
 ### Breaking
 
 The following consists a list of breaking changes from 2.x:
 
-- **keyCode support as `v-on` modifiers.** For more information, [see in-depth explanation](/guides/migration/keycodes.html)
+- [Global Vue API is changed to use an application instance](/guide/migration/global-api.html)
+- [Global and internal APIs have been restructured to be tree-shakable](/guide/migration/treeshaking.html)
+- [`model` component option and `v-bind`'s `sync` modifier are removed in favor of `v-model` arguments](/guide/migration/v-model.html)
+- [Functional components can only be created using a plain function](/guide/migration/functional-components.html)
+- [Async components now require `defineAsyncComponent` method to be created](/guide/migration/async-components.html)
+- [Component data option should always be declared as a function](/guide/migration/data-option.html)
+- [Custom elements whitelisting is now performed during template compilation](/guide/migration/custom-elements-interop.html)
+- [Special `is` prop usage is restricted to the reserved `<component>` tag only](/guide/migration/custom-elements-interop.html)
+
+### Removed
+
+- [`keyCode` support as `v-on` modifiers](/guide/migration/keycodes.html)
+- [$on, $off and $once instance methods](/guide/migration/events-api.html)
+- [Filters](/guide/migration/filters.html)
 
 ## FAQ
 
-> Where should I start in a migration?
+### Where should I start in a migration?
 
-[//]: # 'TODO: update this link when we have a migration helper'
+> Migration helper is still under development
 
 1. Start by running the [migration helper](https://github.com/vuejs/vue-migration-helper) on a current project. We've carefully minified and compressed a senior Vue dev into a simple command line interface. Whenever they recognize an obsolete feature, they'll let you know, offer suggestions, and provide links to more info.
 
@@ -40,18 +51,16 @@ The following consists a list of breaking changes from 2.x:
 
 4. By now, your app should be fully migrated. If you're still hungry for more though, you can read the rest of this page - or dive in to the new and improved guide from [the beginning](index.html). Many parts will be skimmable, since you're already familiar with the core concepts.
 
-> How long will it take to migrate a Vue 2.x app to 3.0?
+### How long will it take to migrate a Vue 2.x app to 3.0?
 
 It depends on a few factors:
 
 - The size of your app (small to medium-sized apps will probably be less than a day)
 
 - How many times you get distracted and start playing with a cool new feature. 😉 &nbsp;Not judging, it also happened to us while building 3.0!
 
-[//]: # 'TODO: update this with link to styleguide'
-
-- Which obsolete features you're using. Most can be upgraded with find-and-replace, but others might take a few minutes. If you're not currently following best practices according to our styleguide, Vue 3.0 will also try harder to force you to. This is a good thing in the long run, but could also mean a significant (though possibly overdue) refactor.
+- Which obsolete features you're using. Most can be upgraded with find-and-replace, but others might take a few minutes. If you're not currently following best practices according to [our styleguide](/style-guide/README.html), Vue 3.0 will also try harder to force you to. This is a good thing in the long run, but could also mean a significant (though possibly overdue) refactor.
 
-> If I upgrade to Vue 3, will I also have to upgrade Vuex and Vue Router?
+### If I upgrade to Vue 3, will I also have to upgrade Vuex and Vue Router?
 
-[//]: # 'TODO: still need to see where this lands'
+Yes, currently both [Vuex](https://github.com/vuejs/vuex/tree/4.0#vuex-4) and [Vue Router](https://github.com/vuejs/vue-router-next) are in beta
