From 35624bea0936a2bccf9b86e61dd35f6a3e0305b6 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Mon, 13 Jul 2020 14:29:07 -0400
Subject: [PATCH 1/3] docs (#152): add render function api changes to migration
 guide

---
 src/.vuepress/config.js                    |   3 +-
 src/guide/migration/render-function-api.md | 139 +++++++++++++++++++++
 2 files changed, 141 insertions(+), 1 deletion(-)
 create mode 100644 src/guide/migration/render-function-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index af6106dce0..8ec1aaba8a 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -93,7 +93,8 @@ const sidebar = {
         'migration/v-model',
         'migration/functional-components',
         'migration/async-components',
-        'migration/custom-directives'
+        'migration/custom-directives',
+        'migration/render-function-api'
       ]
     },
     {
diff --git a/src/guide/migration/render-function-api.md b/src/guide/migration/render-function-api.md
new file mode 100644
index 0000000000..16699afa4a
--- /dev/null
+++ b/src/guide/migration/render-function-api.md
@@ -0,0 +1,139 @@
+# Render Function API
+
+## Overview
+
+This change will not affect `<template>` users.
+
+Here is a quick summary of what has changed:
+
+- `h` is now globally imported instead of passed to render functions as an arguments
+- render function arguments changed to be more consistent between stateful and functional components
+- VNodes now have a flat props structure
+
+For more information, read on!
+
+## Render Function Argument
+
+### Previous Syntax
+
+In 2.x, the `render` function would automatically receive the `h` function (which is a conventional alias for `createElement`).
+
+```js
+// Vue 2 Render Function Example
+export default {
+  render(h) {
+    return h('div')
+  }
+}
+```
+
+### Current Syntax
+
+In 3.x, `h` is now globally imported instead of being automatically passed as an argument.
+
+```js
+// Vue 3 Render Function Example
+import { h } from 'vue'
+
+export default {
+  render() {
+    return h('div')
+  }
+}
+```
+
+## Render Function Signature Change
+
+### Previous Syntax
+
+In 2.x, the `render` function automatically received arguments such as `h`.
+
+```js
+// Vue 2 Render Function Example
+export default {
+  render(h) {
+    return h('div')
+  }
+}
+```
+
+### Current Syntax
+
+In 3.x, since the `render` function no longer receives any arguments, it will primarily be used inside of the `setup()` function. This has the added benefit of gaining access to reactive state and functions declared in scope, as well as the arguments passed to `setup()`.
+
+```js
+import { h, reactive } from 'vue'
+
+export default {
+  setup(props, { slots, attrs, emit }) {
+    const state = reactive({
+      count: 0
+    })
+
+    function increment() {
+      state.count++
+    }
+
+    // return the render function
+    return () => {
+      return h(
+        'div',
+        {
+          onClick: increment
+        },
+        state.count
+      )
+    }
+  }
+}
+```
+
+For more information on how `setup()` works, see our [Composition API Guide](/guide/composition-api-introduction.html).
+
+## VNode Props Format
+
+### Previous Syntax
+
+In 2.x, `domProps` contained a nested list within the VNode props:
+
+```js
+// 2.x
+{
+  class: ['button', 'is-outlined'],
+  style: { color: '#34495E' },
+  attrs: { id: 'submit' },
+  domProps: { innerHTML: '' },
+  on: { click: submitForm },
+  key: 'submit-button'
+}
+```
+
+### Current Syntax
+
+In 3.x, the entire VNode props structure is flattened. Using the example from above, here is what it would look like now.
+
+```js
+// 3.x Syntax
+{
+  class: ['button', 'is-outlined'],
+  style: { color: '#34495E' },
+  attrs: { id: 'submit' },
+  innerHTML: '',
+  on: { click: submitForm },
+  key: 'submit-button'
+}
+```
+
+## How to Migrate
+
+### Library Authors
+
+`h` being globally imported means that any library that contains Vue components will include `import { h } from 'vue'` somewhere. As a result, this creates a bit of overhead since it requires library authors to properly configure the externalization of Vue in their build setup:
+
+- Vue should not be bundled into the library
+- For module builds, the import should be left alone and be handled by the end user bundler
+- For UMD / browser builds, it should try the global Vue.h first and fallback to require calls
+
+## Next Steps
+
+See [Render Function Guide](/guide/render-function) for more detailed documentation!

From 457118d7b7d79bf3e5a4303b6be1ee4d742ac2a9 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Tue, 14 Jul 2020 09:45:37 -0400
Subject: [PATCH 2/3] docs: improve clarity

Co-authored-by: Natalia Tepluhina <tarya.se@gmail.com>
---
 src/guide/migration/render-function-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/migration/render-function-api.md b/src/guide/migration/render-function-api.md
index 16699afa4a..4e17daa66f 100644
--- a/src/guide/migration/render-function-api.md
+++ b/src/guide/migration/render-function-api.md
@@ -16,7 +16,7 @@ For more information, read on!
 
 ### Previous Syntax
 
-In 2.x, the `render` function would automatically receive the `h` function (which is a conventional alias for `createElement`).
+In 2.x, the `render` function would automatically receive the `h` function (which is a conventional alias for `createElement`) as an argument:
 
 ```js
 // Vue 2 Render Function Example

From c3763e55c9f731700fc9be2662165730f38295e4 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Tue, 14 Jul 2020 09:46:17 -0400
Subject: [PATCH 3/3] docs: improve conciseness of code example

Co-authored-by: Natalia Tepluhina <tarya.se@gmail.com>
---
 src/guide/migration/render-function-api.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/guide/migration/render-function-api.md b/src/guide/migration/render-function-api.md
index 4e17daa66f..4210c48a13 100644
--- a/src/guide/migration/render-function-api.md
+++ b/src/guide/migration/render-function-api.md
@@ -75,15 +75,13 @@ export default {
     }
 
     // return the render function
-    return () => {
-      return h(
-        'div',
-        {
-          onClick: increment
-        },
-        state.count
-      )
-    }
+    return () =>  h(
+      'div',
+      {
+        onClick: increment
+      },
+      state.count
+    )
   }
 }
 ```