diff --git a/docs/source/zh-cn/migration.md b/docs/source/zh-cn/migration.md
index 67727cf901..5d2e35241b 100644
--- a/docs/source/zh-cn/migration.md
+++ b/docs/source/zh-cn/migration.md
@@ -19,6 +19,7 @@ title: Egg@2 升级指南
 Egg 的理念之一是`渐进式增强`，故我们为开发者提供`渐进升级`的体验。
 
 - [快速升级](#快速升级)
+- [插件变更说明](#插件变更说明)
 - [进一步升级](#进一步升级)
 - [针对`插件开发者`的升级指南](#插件升级)
 
@@ -29,7 +30,59 @@ Egg 的理念之一是`渐进式增强`，故我们为开发者提供`渐进升
 - 检查相关插件是否发布新版本（可选）。
 - 重新安装依赖，跑单元测试。
 
-**搞定！不需要修改任何一行代码，就已经完成了升级。**
+**搞定！几乎不需要修改任何一行代码，就已经完成了升级。**
+
+
+## 插件变更说明
+
+### egg-multipart
+
+`yield parts` 需修改为 `await parts()` 或 `yield parts()`
+
+```js
+// old
+const parts = ctx.multipart();
+while ((part = yield parts) != null) {
+  // do something
+}
+
+// yield parts() also work
+while ((part = yield parts()) != null) {
+  // do something
+}
+
+// new
+const parts = ctx.multipart();
+while ((part = await parts()) != null) {
+  // do something
+}
+```
+
+- [egg-multipart#upload-multiple-files](https://github.com/eggjs/egg-multipart#upload-multiple-files)
+
+### egg-userrole
+
+不再兼容 1.x 形式的 role 定义，因为 koa-roles 已经无法兼容了。
+请求上下文 `Context` 从 this 传入改成了第一个参数 `ctx` 传入，原有的 `scope` 变成了第二个参数。
+
+```js
+// old
+app.role.use('user', function() {
+  return !!this.user;
+});
+
+// new
+app.role.use((ctx, scope) => {
+  return !!ctx.user
+});
+
+app.role.use('user', ctx => {
+  return !!ctx.user;
+});
+```
+
+- [koajs/koa-roles#13](https://github.com/koajs/koa-roles/pull/13)
+- [eggjs/egg-userrole#9](https://github.com/eggjs/egg-userrole/pull/9)
 
 ## 进一步升级
 
@@ -233,8 +286,10 @@ task = app.toAsyncFunction(schedule.task);
   - 修改 `engines.node` 为 `>=8.0.0`。
   - 修改 `ci.version` 为 `8, 9`， 并重新安装依赖以便生成新的 travis 配置文件。
 - 修改 `README.md` 的示例为 async function。
+- 编写升级指引。
 - 修改 `test/fixtures` 为 async function，可选，建议分开另一个 PR 方便 Review。
 
+
 一般还会需要继续维护上一个版本，故需要：
   - 对上一个版本建立一个 `1.x` 这类的 branch 分支
   - 修改上一个版本的 `package.json` 的 `publishConfig.tag` 为 `release-1.x`