📝 Add migration guide.

Author: AlexV525

README-ZH.md

@@ -17,6 +17,7 @@ Language: [English](README.md) | 中文简体
 
 ## 目录 🗂
 
+* [迁移指南](#迁移指南-)
 * [特性](#特性-)
 * [截图](#截图-)
 * [准备工作](#准备工作-)
@@ -38,6 +39,10 @@ Language: [English](README.md) | 中文简体
   * [从`File`或`Uint8List`创建`AssetEntity`的方法](#从file或uint8list创建assetentity的方法)
   * [控制台提示 'Failed to find GeneratedAppGlideModule'](#控制台提示-failed-to-find-generatedappglidemodule)
 
+## 迁移指南 ♻️
+
+查看 [迁移指南](docs/migration_guide.md).
+
 ## 特性 ✨
 
 - [x] 💚 99%的微信风格

README.md

@@ -38,6 +38,7 @@ This project follows the [all-contributors](https://github.com/all-contributors/
 
 ## Category 🗂
 
+* [Migration Guide](#migration-guide-)
 * [Features](#features-)
 * [Screenshots](#screenshots-)
 * [Preparing for use](#preparing-for-use-)
@@ -59,6 +60,10 @@ This project follows the [all-contributors](https://github.com/all-contributors/
   * [Create `AssetEntity` from `File` or `Uint8List` (rawData)](#create-assetentity-from-file-or-uint8list-rawdata)
   * [Console warning 'Failed to find GeneratedAppGlideModule'](#glide-warning-failed-to-find-generatedappglidemodule)
 
+## Migration Guide ♻️
+
+See [Migration Guide](docs/migration_guide.md).
+
 ## Features ✨
 
 - [x] 💚 99% simillar to WeChat style.

docs/migration_guide.md

@@ -0,0 +1,33 @@
+# Migration Guide
+
+## Migrate to 5.0.0
+
+### Summary
+
+_If you only use the `AssetPicker.pickAssets` and `AssetEntityImageProvider`,
+didn't use `AssetPickerViewer`, `AssetPickerProvider`, or other components separately,
+you can stop reading._
+
+`AssetPicker` and `AssetPickerViewer` are only a builder since 5.x, all widgets construct were moved
+to `AssetPickerBuilderDelegate` and `AssetPickerViewerBuilderDelegate`, and these delegates are both
+abstract.
+
+By splitting delegates, now you can build your own picker with custom types, style, and widgets.
+
+### Migration steps
+
+For how to implement a custom picker, see the example's custom page for more implementation details.
+
+* If you have ever use `AssetPickerViewer.pushToViewer`, the properties `assets` has changed to
+  `previewAssets`.
+
+* If you have extends an `AssetPickerProvider` or `AssetPickerViewerProvider`, it now requires you
+  to pass generic type `A` and `P`, and handle the entities on your own.
+
+### References
+
+API documentation:
+* `AssetPickerBuilderDelegate`: https://pub.dev/documentation/wechat_assets_picker/latest/wechat_assets_picker/AssetPickerBuilderDelegate-class.html
+* `AssetPickerViewerBuilderDelegate`: https://pub.dev/documentation/wechat_assets_picker/latest/wechat_assets_picker/AssetPickerViewerBuilderDelegate-class.html
+* `AssetPickerProvider`: https://pub.dev/documentation/wechat_assets_picker/latest/wechat_assets_picker/AssetPickerProvider-class.html
+* `AssetPickerViewerProvider`: https://pub.dev/documentation/wechat_assets_picker/latest/wechat_assets_picker/AssetPickerViewerProvider-class.html

lib/src/delegates/asset_picker_builder_delegate.dart

@@ -12,6 +12,12 @@ import 'package:flutter/services.dart';
 
 import '../constants/constants.dart';
 
+/// The delegate to build the whole picker's components.
+///
+/// By extending the delegate, you can customize every components on you own.
+/// Delegate requires two generic types:
+///  * [A] "Asset": The type of your assets. Defaults to [AssetEntity].
+///  * [P] "Path": The type of your paths. Defaults to [AssetPathEntity].
 abstract class AssetPickerBuilderDelegate<A, P> {
   AssetPickerBuilderDelegate({
     @required this.provider,

lib/src/provider/asset_picker_provider.dart

@@ -10,7 +10,10 @@ import 'package:flutter/material.dart';
 import '../constants/constants.dart';
 
 /// [ChangeNotifier] for assets picker.
-/// 资源选择器的 provider model
+///
+/// The provider maintain all methods that control assets and paths.
+/// By extending it you can customize how you can get all assets or paths,
+/// how to fetch the next page of assets, how to get the thumb data of a path.
 abstract class AssetPickerProvider<A, P> extends ChangeNotifier {
   /// Call [getAssetList] with route duration when constructing.
   /// 构造时根据路由时长延时获取资源