From de8d3d86a304f0fe0bec816e27c1acbd06e4a96a Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Mon, 6 Jul 2020 12:06:52 -0400
Subject: [PATCH 1/3] docs (#134): add functional components to migration guide

---
 src/.vuepress/config.js                      |  2 +-
 src/guide/migration/functional-components.md | 74 ++++++++++++++++++++
 2 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 src/guide/migration/functional-components.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 942e852a29..50163185c0 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -75,7 +75,7 @@ const sidebar = {
     {
       title: 'Migration to Vue 3',
       collapsable: true,
-      children: ['migration']
+      children: ['migration', 'migration/functional-components']
     },
     {
       title: 'Contribute to the Docs',
diff --git a/src/guide/migration/functional-components.md b/src/guide/migration/functional-components.md
new file mode 100644
index 0000000000..4588e358c0
--- /dev/null
+++ b/src/guide/migration/functional-components.md
@@ -0,0 +1,74 @@
+# Functional Components
+
+## Overview
+
+In terms of what has changed, at a high level:
+
+For more context, be sure to read the rest of the guide.
+
+## Introduction
+
+In Vue 2, functional components had primary use cases:
+
+- as a performance optimization, because they initialized much faster than stateful components
+- to return multiple root nodes
+
+However, in Vue 3, the performance of stateful components has improved to the point that the difference is negligible. In addition, stateful components now also include the ability to return multiple root nodes.
+
+As a result, the only remaining use case for functional components is simple components, such as a component to create a dynamic heading. Otherwise, it is recommended to use stateful components as you normally would.
+
+## Previous Syntax
+
+Using the `<dynamic-heading>` component, which is responsible for rendering out the appropriate heading (i.e., `h1`, `h2`, `h3`, etc.), this could have been written as a single-file component in v2 as:
+
+```js
+// Vue 2 Functional Component Example
+export default {
+  functional: true,
+  props: ['level'],
+  render(h, { props, data, children }) {
+    return h(`h${props.level}`, data, children)
+  }
+}
+```
+
+Or, for those who preferred the `<template>` in a single-file component:
+
+```js
+// Vue 2 Functional Component Example with <template>
+<template functional>
+  <component
+    v-bind:is="`h${props.level}`"
+    v-bind="attrs"
+    v-on="listeners"
+  />
+</template>
+
+<script>
+export default {
+  props: ['level']
+}
+</script>
+
+```
+
+## Current Syntax
+
+Now in Vue 3, the only way to create a functional component is with a plain function that receives `props` and a `context` object that contains `attrs`, `slots`, and `emit` options:
+
+```js
+import { h } from 'vue'
+
+const DynamicHeading = (props, context) => {
+  return h(`h${level}`, context.attrs, context.slots)
+}
+
+DynamicHeading.props = ['level']
+
+export default GreetingMessage
+```
+
+For more information on the usage of the new functional components and the changes to render functions in general, see:
+
+- [Migration: Render Functions](TODO)
+- [Guide: Render Functions](/guide/render-function.html)

From 2c549e85ca20a2d525701af74438d91376268b71 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Mon, 6 Jul 2020 12:13:45 -0400
Subject: [PATCH 2/3] docs (#134): update overview section for functional
 components migration

---
 src/guide/migration/functional-components.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/guide/migration/functional-components.md b/src/guide/migration/functional-components.md
index 4588e358c0..4ab880654e 100644
--- a/src/guide/migration/functional-components.md
+++ b/src/guide/migration/functional-components.md
@@ -4,7 +4,11 @@
 
 In terms of what has changed, at a high level:
 
-For more context, be sure to read the rest of the guide.
+- Performance gains from v2 for functional components are now negligible in v3, so we recommend just using stateful components
+- `functional` attribute on single-file component `<template>` is deprecated
+- Functional components can only be created using a plain function that receives `props` and `context` (i.e., `slots`, `attrs`, `emit`)
+
+For a more in-depth explanation, please continue reading on!
 
 ## Introduction
 

From 3b069b4ccbdd30490814b24a689e264d6ac0970c Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Mon, 6 Jul 2020 23:16:35 -0400
Subject: [PATCH 3/3] docs: improve phrasing

Co-authored-by: Phan An <me@phanan.net>
---
 src/guide/migration/functional-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/migration/functional-components.md b/src/guide/migration/functional-components.md
index 4ab880654e..31b2bd8086 100644
--- a/src/guide/migration/functional-components.md
+++ b/src/guide/migration/functional-components.md
@@ -8,7 +8,7 @@ In terms of what has changed, at a high level:
 - `functional` attribute on single-file component `<template>` is deprecated
 - Functional components can only be created using a plain function that receives `props` and `context` (i.e., `slots`, `attrs`, `emit`)
 
-For a more in-depth explanation, please continue reading on!
+For a more in-depth explanation, read on!
 
 ## Introduction