Merge branch 'master' of github.com:vuejs/docs-next

Author: NataliaTepluhina

.github/pull_request_template.md

@@ -1,9 +1,5 @@
-# ⚠️⚠️⚠️ DISCLAIMER ⚠️⚠️⚠️:
+## Description of Problem
 
-Thanks for your interest in submitting a PR! At this time, because the docs are in beta, the team is currently in the midst of changes. As a result, **we are not ready for additional contributions yet**.
+## Proposed Solution
 
-## How can I provide feedback?
-
-To be respectful of your time and ideas, **please [create an issue](https://github.com/vuejs/docs-next/issues/new) instead of a pull request**. Otherwise, we will have to simply close your pull request at this time.
-
-Thanks for your understanding!
+## Additional Information

src/.vuepress/components/BetaBanner.vue renamed to src/.vuepress/components/AppBanner.vue

@@ -1,11 +1,7 @@
 <template>
   <ClientOnly>
-    <aside class="beta-banner" v-if="shouldShow">
-      <p>
-        <span class="hide-sm">⚠️ Beta Version:</span>
-        Docs
-        <span class="hide-sm">are</span> in development and subject to change.
-      </p>
+    <aside class="app-banner" v-if="shouldShow">
+      <slot></slot>
       <button ref="closeButton" @click="close">Close</button>
     </aside>
   </ClientOnly>
@@ -39,7 +35,7 @@ export default {
 <style lang="scss" scoped>
 @import '../theme/styles/mixins.scss';
 
-.beta-banner {
+.app-banner {
   position: fixed;
   z-index: 21;
   top: 0;

src/.vuepress/components/common/vuemastery-video-modal.vue

@@ -3,7 +3,7 @@
     <div ref="modal" class="modal" :class="{ open: isOpen }">
       <div class="video-space" style="padding: 56.25% 0 0 0; position: relative;">
         <iframe
-          src="https://player.vimeo.com/video/247494684?dnt=1"
+          src="https://player.vimeo.com/video/455611549?dnt=1"
           style="height: 100%; left: 0; position: absolute; top: 0; width: 100%; margin: 0"
           frameborder="0"
           webkitallowfullscreen
@@ -23,7 +23,7 @@
         >Vue Mastery</a>.
         Watch Vue Mastery’s free
         <a
-          href="https://www.vuemastery.com/courses/intro-to-vue-js/vue-instance/"
+          href="https://www.vuemastery.com/courses/intro-to-vue-3/intro-to-vue3"
           target="_blank"
           rel="sponsored noopener"
           title="Vue.js Courses on Vue Mastery"

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',

src/.vuepress/theme/layouts/Layout.vue

@@ -5,7 +5,6 @@
     @touchstart="onTouchStart"
     @touchend="onTouchEnd"
   >
-    <BetaBanner />
     <Navbar v-if="shouldShowNavbar" @toggle-sidebar="toggleSidebar" />
 
     <div class="sidebar-mask" @click="toggleSidebar(false)" />

src/guide/contributing/translations.md

@@ -4,8 +4,8 @@ Vue has spread across the globe, with the core team being in at least half a doz
 
 ## Can we start translating Vue 3 docs?
 
-At this time, the Vue 3 docs are still in beta and subject to changes at any time. As a result, we would caution against any significant work since we are still collecting feedback and rewriting it as needed. When the docs are in release candidate phase, we will make sure to make an announcement so you can get started!
+Yes! We are ready for translation!
 
 ## How can I get involved with translations?
 
-The best way to get started is to check out [this pinned issue for Vuejs.org](https://github.com/vuejs/vuejs.org/issues/2015) that contains active discussions on the various initiatives happening in the community.
+The best way to get started is to check out [this pinned issue](https://github.com/vuejs/docs-next/issues/478) that contains active discussions on the various initiatives happening in the community.

src/guide/events.md

@@ -1,7 +1,5 @@
 # Event Handling
 
-<div class="vueschool"><a href="https://vueschool.io/lessons/vuejs-user-events?friend=vuejs" target="_blank" rel="sponsored noopener" title="Learn how to handle events on Vue School">Learn how to handle events in a free Vue School lesson</a></div>
-
 ## Listening to Events
 
 We can use the `v-on` directive, which we typically shorten to the `@` symbol, to listen to DOM events and run some JavaScript when they're triggered. The usage would be `v-on:click="methodName"` or with the shortcut, `@click="methodName"`

src/guide/installation.md

@@ -2,7 +2,8 @@
 
 ## Release Notes
 
-Latest beta version: 3.0.0-rc.5
+Latest beta version: ![beta](https://img.shields.io/npm/v/vue/next.svg)
+
 
 Detailed release notes for each version are available on [GitHub](https://github.com/vuejs/vue-next/releases).
 

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

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>
+```