From 87a20bd8730ce5681408ffa86fd4db2fb7812627 Mon Sep 17 00:00:00 2001
From: Peach <scdzwyxst@gmail.com>
Date: Fri, 26 Aug 2022 16:12:19 +0800
Subject: [PATCH] docs: add more guide docs (umijs/father-next#68)

* docs: add more guide docs

* docs: typo & link

* docs: use same text

* Update docs/guide/pre-bundle.md

Co-authored-by: wangxingkang <wang_xingkang@qq.com>

* docs: add migrade guide

* docs: update readme

Co-authored-by: wangxingkang <wang_xingkang@qq.com>
---
 README.md                |  21 ++++-
 docs/guide.md            |  38 +--------
 docs/guide/build-mode.md |  90 ++++++++++++++++++++
 docs/guide/dev.md        |  27 ++++++
 docs/guide/doctor.md     |  65 +++++++++++++++
 docs/guide/esm-cjs.md    |  44 ++++++++++
 docs/guide/index.md      |  46 +++++++++++
 docs/guide/migrate.md    | 172 +++++++++++++++++++++++++++++++++++++++
 docs/guide/pre-bundle.md |  33 ++++++++
 docs/guide/release.md    |  42 ++++++++++
 docs/guide/umd.md        |  26 ++++++
 11 files changed, 565 insertions(+), 39 deletions(-)
 mode change 100644 => 120000 docs/guide.md
 create mode 100644 docs/guide/build-mode.md
 create mode 100644 docs/guide/dev.md
 create mode 100644 docs/guide/doctor.md
 create mode 100644 docs/guide/esm-cjs.md
 create mode 100644 docs/guide/index.md
 create mode 100644 docs/guide/migrate.md
 create mode 100644 docs/guide/pre-bundle.md
 create mode 100644 docs/guide/release.md
 create mode 100644 docs/guide/umd.md

diff --git a/README.md b/README.md
index ace0e883..75600378 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,22 @@
 # father
 
-[![version](https://badgen.net/npm/v/father/next)](https://www.npmjs.com/package/father) [![codecov](https://codecov.io/gh/umijs/father-next/branch/master/graph/badge.svg)](https://codecov.io/gh/umijs/father-next) [![GitHub Actions status](https://github.com/umijs/father-next/workflows/CI/badge.svg)](https://github.com/umijs/father-next)
+[![version](https://badgen.net/npm/v/father)](https://www.npmjs.com/package/father) [![codecov](https://codecov.io/gh/umijs/father/branch/master/graph/badge.svg)](https://codecov.io/gh/umijs/father) [![GitHub Actions status](https://github.com/umijs/father/workflows/CI/badge.svg)](https://github.com/umijs/father)
 
-Now father@4 RC version is available, you can try it with our docs: [中文](./docs/guide.md)
+father 是一款 NPM 包研发工具，能够帮助开发者更高效、高质量地研发 NPM 包、生成构建产物、再完成发布。它主要具备以下特性：
+
+- ⚔️ **双模式构建：** 支持 Bundless 及 Bundle 两种构建模式，ESModule 及 CommonJS 产物使用 Bundless 模式，UMD 产物使用 Bundle 模式
+- 🎛 **多构建核心：** Bundle 模式使用 Webpack 作为构建核心，Bundless 模式使用 esbuild 及 Babel 两种构建核心，可通过配置自由切换
+- 🔖 **类型生成：** 无论是源码构建还是依赖预打包，都支持为 TypeScript 模块生成 `.d.ts` 类型定义
+- 🩺 **项目体检：** 对 NPM 包研发常见误区做检查，让每一次发布都更加稳健
+- 🏗 **微生成器：** 为项目追加生成常见的工程化能力，例如使用 jest 编写测试
+- 📦 **依赖预打包：** 开箱即用的依赖预打包能力，帮助 Node.js 框架/库提升稳定性、不受上游依赖更新影响（实验性）
+
+访问 [指南](./docs/guide/index.md) 及 [配置项](./docs/config.md) 了解更多。
+
+## 贡献指南
+
+查看 [CONTRIBUTING](./CONTRIBUTING.md) 文档。
+
+## License
+
+[MIT](./LICENSE)
diff --git a/docs/guide.md b/docs/guide.md
deleted file mode 100644
index bbd0d3a6..00000000
--- a/docs/guide.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# 指南
-
-## 介绍
-
-father 是一款组件/库打包工具，可以帮助开发者将项目源码输出为 ESModule/CommonJS/UMD 产物用于 NPM 包发布，并且还内置了开箱即用的依赖预打包能力。
-
-## 快速上手
-
-通过 `create-father` 快速创建一个 father 项目：
-
-```bash
-$ npx create-father test-father-4
-```
-
-脚手架中仅包含最基础的配置，更多配置项及作用可以参考 [配置项文档](./config.md)。
-
-执行构建：
-
-```bash
-# 执行全量构建并 watch 变更做增量构建，仅支持 esm/cjs 产物
-$ npx father dev
-
-# 执行全量构建
-$ npx father build
-
-# 执行依赖预打包
-$ npx father prebundle
-```
-
-执行项目检查：
-
-```bash
-# 检查项目的潜在问题
-$ npx father doctor
-```
-
-验证产物并发布 NPM 包。
diff --git a/docs/guide.md b/docs/guide.md
new file mode 120000
index 00000000..f7bec66e
--- /dev/null
+++ b/docs/guide.md
@@ -0,0 +1 @@
+./guide/index.md
\ No newline at end of file
diff --git a/docs/guide/build-mode.md b/docs/guide/build-mode.md
new file mode 100644
index 00000000..0a42a970
--- /dev/null
+++ b/docs/guide/build-mode.md
@@ -0,0 +1,90 @@
+# 构建模式
+
+## Bundless
+
+Bundless 即文件到文件的构建模式，它不对依赖做任何处理，只对源码做平行编译输出。目前社区里的 [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html)、[unbuild](https://github.com/unjs/unbuild) 及旧版 father 的 babel 模式都是对源码做 Bundless 构建的构建工具。
+
+在 father 4 中，输出 ESModule 产物和 CommonJS 产物时都会采用 Bundless 构建模式，来看一下 father 的 Bundless 构建模式会如何工作。
+
+假定有这样的源码结构：
+
+```bash
+.
+└── src
+    ├── index.less
+    ├── index.tsx
+    └── util.js
+```
+
+配合以下构建配置：
+
+```js
+export default {
+  esm: { output: 'dist' },
+  // 或者
+  cjs: { output: 'dist' },
+};
+```
+
+则会被 father 输出为：
+
+```bash
+.
+└── dist
+    ├── index.d.ts
+    ├── index.js
+    ├── index.less
+    └── util.js
+```
+
+可以发现，在 Bundless 模式下，father 对源码的处理逻辑如下：
+
+1. TypeScript 模块会被编译为 JavaScript 模块，并且输出对应的 `.d.ts` 类型文件
+2. JavaScript 模块会被编译为 JavaScript 模块，做兼容性处理
+3. 其他模块会被直接拷贝输出，不做编译
+
+### 如何选择
+
+Bundless 模式下的产物可以被项目选择性引入，同时也具备更好的可调试性。对于大部分项目而言，Bundless 应该都是最好的选择，这也是社区大部分项目的选择。
+
+关于如何选择 ESModule 产物和 CommonJS 产物，可参考 [构建 ESModule 和 CommonJS 产物](./esm-cjs.md#如何选择) 文档。
+
+## Bundle
+
+Bundle 即将源码打包的构建模式，它以入口文件作为起点、递归处理全部的依赖，然后将它们合并输出成构建产物。目前社区里的 [Webpack](https://webpack.js.org)、[Rollup](https://rollupjs.org/guide/en/) 及旧版 father 的 rollup 模式都是对源码做 Bundle 构建的构建工具。
+
+在 father 4 中，仅输出 UMD 产物时会使用 Bundle 构建模式。来看一下 father 的 Bundle 构建模式会如何工作。
+
+假定有这样的源码结构：
+
+```bash
+.
+└── src
+    ├── index.less
+    └── index.tsx # 源码中引入 index.less
+```
+
+配合以下构建配置：
+
+```ts
+export default {
+  umd: { output: 'dist' },
+};
+```
+
+则会被 father 输出为：
+
+```bash
+.
+└── dist
+    ├── index.min.js
+    └── index.min.css
+```
+
+可以发现，在 Bundless 模式下，father 会对源码进行打包，最后输出压缩后的 JavaScript 产物和 CSS 产物。
+
+### 如何选择
+
+Bundle 的产物具备更好的一体性。father 中只有 UMD 产物是 Bundle 构建模式，所以在需要 UMD 产物时就随之选择了 Bundle 构建模式。
+
+关于何时选择 UMD 产物，可参考 [构建 UMD 产物](./umd.md#如何选择) 文档。
diff --git a/docs/guide/dev.md b/docs/guide/dev.md
new file mode 100644
index 00000000..6a8af33d
--- /dev/null
+++ b/docs/guide/dev.md
@@ -0,0 +1,27 @@
+# 开发
+
+将构建配置设置完毕后，即可开始开发。
+
+## 实时编译产物
+
+开发过程中我们需要实时编译产物，以便进行调试、验证：
+
+```bash
+# 执行 dev 命令，开启实时编译
+$ father dev
+```
+
+一旦源码或配置文件发生变化，产物将会实时增量编译到输出目录。
+
+> 注：目前仅 Bundless 模式支持实时编译
+
+## 在项目中调试
+
+在测试项目中，使用 `npm link` 命令将该项目链接到测试项目中进行调试、验证：
+
+```bash
+$ cd test-project
+$ npm link /path/to/your-father-project .
+```
+
+开发、验证完成后，即可 [发布](./release.md) 该 NPM 包。
diff --git a/docs/guide/doctor.md b/docs/guide/doctor.md
new file mode 100644
index 00000000..2b020f02
--- /dev/null
+++ b/docs/guide/doctor.md
@@ -0,0 +1,65 @@
+# 项目体检
+
+father 的项目体检能力可以帮助我们发现项目的潜在问题，并提供改进建议，只需执行：
+
+```bash
+$ father doctor
+```
+
+目前包含如下规则。
+
+## PACK_FILES_MISSING
+
+- 级别：错误 ❌
+- 说明：
+
+有配置 files 字段但却不包含构建产物目录，这会导致发布后的 NPM 包找不到对应的模块。
+
+## EFFECTS_IN_SIDE_EFFECTS
+
+- 级别：错误 ❌
+- 说明：
+
+`package.json` 文件中的 `sideEffects` 字段配置有误，例如：
+
+1. 构建产物里有引入样式文件，却将 `sideEffects` 配置为 `false`，这会导致实际项目编译后丢失样式
+2. 使用了 Rollup.js 不兼容的通配方式 `*.css`，这在 Webpack 项目中意味着匹配全部的 CSS，但在 Rollup.js 项目中意味着顶层的 CSS
+
+## PHANTOM_DEPS
+
+- 级别：错误 ❌
+- 说明：
+
+源码中使用了某个依赖，但却没有声明在 `dependencies` 中，这会导致项目引用到[幽灵依赖](https://rushjs.io/pages/advanced/phantom_deps/)，它可能不存在，也可能是错误的版本，使得项目存在运行失败的风险。
+
+## PREFER_PACK_FILES
+
+- 级别：警告 ⚠️
+- 说明：
+
+建议使用 `files` 字段声明要发布到 NPM 的文件，以减小 NPM 包安装体积。
+
+## PREFER_NO_CSS_MODULES
+
+- 级别：警告 ⚠️
+- 说明：
+
+不建议使用 CSS Modules，用户难以覆写样式，且会给用户项目增加额外的编译成本
+
+## PREFER_BABEL_RUNTIME
+
+- 级别：警告 ⚠️
+- 说明：
+
+建议安装 `@babel/runtme` 到 `dependencies`，以节省构建产物大小。
+
+> 注：该规则仅在 `transformer` 是 `babel` 且 `platform` 是 `browser` 时生效
+
+## DUP_IN_PEER_DEPS
+
+- 级别：警告 ⚠️
+- 说明：
+
+`peerDependencies` 和 `dependencies` 里有相同依赖，建议根据项目实际需要去掉其中一个。
+
+如果你有其他的 NPM 包的研发建议，欢迎评论到 [issue](https://github.com/umijs/father-next/issues/36) 中，规则讨论通过后将会被添加。
diff --git a/docs/guide/esm-cjs.md b/docs/guide/esm-cjs.md
new file mode 100644
index 00000000..accf083d
--- /dev/null
+++ b/docs/guide/esm-cjs.md
@@ -0,0 +1,44 @@
+# 构建 ESModule 与 CommonJS 产物
+
+> 在 father 项目中，ESModule 产物构建与 CommonJS 产物构建类似，所以本章做合并介绍。
+
+## 如何选择
+
+ESModule 是 JavaScript 使用的模块规范，而 CommonJS 是 Node.js 使用的模块规范，这我们已经很熟悉了，所以我们的项目需要输出什么产物，只需要根据使用情况判断即可：
+
+| 产物类型/运行环境 | Browser | Node.js  | Both    |
+| ----------------- | ------- | -------- | ------- |
+| ESModule          | ✅ 推荐 | 暂不推荐 | ✅ 推荐 |
+| CommonJS          | 没必要  | ✅ 推荐  | ✅ 推荐 |
+
+额外说明：
+
+1. 由于 Node.js 社区的 Pure ESM 推进[仍有阻碍](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)，所以为了通用性考虑，目前仍然建议大家为 Node.js 项目产出 CommonJS 产物，未来 father 也会推出同时产出 ESModule 产物的兼容方案，敬请期待
+2. 对于 Browser 运行环境，CommonJS 产物是没必要的，无论哪种模块构建工具都能帮我们解析，加上 Vite 这类使用原生 ESModule 产物的构建工具已经成熟，使用 ESModule 才是面向未来的最佳选择
+3. Both 是指构建产物要同时用于 Browser 和 Node.js 的项目，比如 react-dom、umi 等
+
+## 如何构建
+
+只需要使用 `esm` 及 `cjs` 配置项，再执行 `father build` 即可产出 ESModule 和 CommonJS 产物：
+
+```js
+// .fatherrc.js
+export default {
+  // 以下为 esm 配置项启用时的默认值，有自定义需求时才需配置
+  esm: {
+    input: 'src', // 默认编译目录
+    target: 'browser', // 默认构建为 Browser 环境的产物
+    transformer: 'babel', // 默认使用 babel 以提供更好的兼容性
+  },
+  // 以下为 cjs 配置项启用时的默认值，有自定义需求时才需配置
+  cjs: {
+    input: 'src', // 默认编译目录
+    target: 'node', // 默认构建为 Node.js 环境的产物
+    transformer: 'esbuild', // 默认使用 esbuild 以获得更快的构建速度
+  },
+};
+```
+
+更多配置项可参考 [配置项](../config.md)。
+
+在 father 项目中，ESModule 产物及 CommonJS 产物都以 Bundless 模式进行构建，关于 Bundless 模式的介绍可参考 [构建模式 - Bundless](./build-mode.md#bundless)。
diff --git a/docs/guide/index.md b/docs/guide/index.md
new file mode 100644
index 00000000..b717503c
--- /dev/null
+++ b/docs/guide/index.md
@@ -0,0 +1,46 @@
+# 指南
+
+## 介绍
+
+father 是一款 NPM 包研发工具，能够帮助开发者更高效、高质量地研发 NPM 包、生成构建产物、再完成发布。它主要具备以下特性：
+
+- ⚔️ **双模式构建：** 支持 Bundless 及 Bundle 两种构建模式，ESModule 及 CommonJS 产物使用 Bundless 模式，UMD 产物使用 Bundle 模式
+- 🎛 **多构建核心：** Bundle 模式使用 Webpack 作为构建核心，Bundless 模式使用 esbuild 及 Babel 两种构建核心，可通过配置自由切换
+- 🔖 **类型生成：** 无论是源码构建还是依赖预打包，都支持为 TypeScript 模块生成 `.d.ts` 类型定义
+- 🩺 **项目体检：** 对 NPM 包研发常见误区做检查，让每一次发布都更加稳健
+- 🏗 **微生成器：** 为项目追加生成常见的工程化能力，例如使用 jest 编写测试
+- 📦 **依赖预打包：** 开箱即用的依赖预打包能力，帮助 Node.js 框架/库提升稳定性、不受上游依赖更新影响（实验性）
+
+## 兼容性
+
+father 本身需要在 Node.js v14 以上的环境中运行，使用前请确保已安装 Node.js v14 及以上版本。
+
+father 产出的 Node.js 产物默认兼容到 Node.js v14，Browser 产物默认兼容到 ES5（IE11），暂不支持修改。
+
+## 快速上手
+
+通过 `create-father` 快速创建一个 father 项目：
+
+```bash
+$ npx create-father my-father-project
+```
+
+> 脚手架中仅包含最基础的配置，更多配置项及作用可以参考 [配置项文档](./config.md)。
+
+执行构建：
+
+```bash
+$ npx father build
+```
+
+查看 `dist` 文件夹，可以看到构建产物已被生成出来。恭喜你，已经完成了第一个 father 项目的构建工作 🎉
+
+接下来，你可以查看其它文档了解 father 的更多功能：
+
+- [Bundless 与 Bundle 构建模式](./build-mode.md)
+- [构建 ESModule 和 CommonJS 产物](./esm-cjs.md)
+- [构建 UMD 产物](./umd.md)
+- [依赖预打包](./pre-bundle.md)
+- [执行项目体检](./doctor.md)
+- [开发指南](./dev.md)
+- [发布指南](./release.md)
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
new file mode 100644
index 00000000..1592d57d
--- /dev/null
+++ b/docs/guide/migrate.md
@@ -0,0 +1,172 @@
+# 从 father v2 或 father-build v1 迁移
+
+> 注：father v2 = father-build v1 + 文档能力 + 其他工程化能力，两者在构建功能上是一回事
+
+按照如下步骤，可手动将组件库构建从 father v2 或 father-build v1 升级到 father 4
+
+## 不兼容变更
+
+1. **不再支持所有 rollup 构建模式**，如果项目源码需要打包，请输出 UMD 构建产物（基于 Webpack）；如果不需要打包，请以 Bundless 形式输出 ESModule 或 CommonJS 产物（基于 Babel/esbuild），具体可参考 [构建模式](./build-mode.md) 文档
+2. **不再内置 CSS Modules 支持**，组件库不建议使用 CSS Modules，会使得样式难以覆写、且会给用户项目带来额外的编译成本
+3. **Bundless 模式不再支持编译非 JavaScript 文件**，样式表交给实际项目编译会更加灵活，如果组件库有自定义主题的需求，可以考虑使用输出 UMD 产物，具体可参考 [构建 UMD 产物 - 如何选择](./umd.md#如何选择)
+4. **不再内置组件库文档方案**，如果此前使用 Docz 文档方案，请参考 [文档](https://github.com/umijs/father/issues/241) 迁移到 dumi；如果是新项目，可以直接使用 [dumi 组件研发脚手架](https://d.umijs.org/zh-CN/guide#%E8%84%9A%E6%89%8B%E6%9E%B6%E5%88%9D%E5%A7%8B%E5%8C%96) 初始化项目；未来 dumi 2 会和 father 4 一起提供更加集成化的组件研发方案
+5. **不再内置 monorepo 支持**，请将 father 4 结合各 monorepo 自己的方案做源码构建，比如 pnpm workspace 可参考 [Umi 4 的仓库](https://github.com/umijs/umi)
+
+## package.json 升级
+
+```diff
+{
+  "scripts": {
++   "dev": "father dev",
+    "build": "father build",
+    ...
+  },
+  "devDependencies": {
+    ...
+-   "father": "^2.0.0"
++   "father": "^4.0.0"
+  }
+}
+```
+
+## 配置文件升级
+
+首先，建议从 `.fatherrc.js` 改用 `.fatherrc.ts`，以获得配置的自动补全，然后将各项配置做更新升级：
+
+```diff
++ import { defineConfig } from 'father';
+
+- export default {
++ export default defineConfig({
+    ...
+- }
++ });
+```
+
+### 废弃的配置项
+
+```diff
+export default defineConfig({
+  cjs: {
+    # 已废弃，Bundless 构建模式不需要指定输出文件
+-   file: 'xxx',
+    # 已废弃，不支持配置
+-   lazy: true,
+    # 已废弃，Bundless 构建模式不压缩
+-   minify: true,
+  },
+  esm: {
+    # 已废弃，Bundless 构建模式不需要指定输出文件
+-   file: 'xxx',
+    # 已废弃，后续会提供更简单的 pure esm 方案
+-   mjs: true,
+    # 已废弃，Bundless 构建模式不压缩
+-   minify: true,
+  },
+  umd: {
+    # 已废弃，会自动复用 entry 文件名，有特殊需要可走 chainWebpack 配置
+-   file: 'xxx',
+    # 已废弃，统一生成 min 版本
+-   minFile: true,
+    # 暂不支持，有特殊需要可走 chainWebpack 配置
+-   sourcemap: true,
+  },
+  # 已废弃，不支持配置
+- cssModules: true,
+  # 已废弃，不允许关闭类型检查
+- disableTypeCheck: true,
+  # 已废弃，请迁移到 dumi
+- doc: {},
+  # 已废弃，不支持配置
+- file: 'xxx',
+  # 已废弃，Bundless 模式不再编译非 JavaScript 文件
+- lessInBabelMode: {},
+  # 已废弃，默认兼容到 Node.js v14，暂不支持配置
+- nodeVersion: 14,
+  # 已废弃，改为约定式，只要 dependencies 里包含 @babel/runtime 则默认为 true
+- runtimeHelpers: true,
+  # 已废弃，默认提取 CSS 为单独文件，有特殊需要可走 chainWebpack 配置
+- extractCSS: true,
+- injectCSS: true,
+  # 已废弃，不再关心 monorepo
+- pkgFilter: {},
+- pkgs: [],
+  # 已废弃，Rollup 特定配置项均不支持配置
+- extraRollupPlugins: [],
+- include: {},
+- lessInRollupMode: {},
+- nodeResolveOpts: {},
+- sassInRollupMode: {},
+});
+```
+
+### 更新的配置项
+
+```diff
+export default defineConfig({
+  esm: {
+    # 改用 alias: { 'antd/lib' : 'antd/es' } 代替
+-   importLibToEs: true,
+    # 用 transformer 配置项代替，可选值参考配置项文档
+-   type: 'rollup',
+    # 默认值为 dist/esm，如果想保持原目录，需增加 output 配置项
++   output: 'es'
+  },
+  cjs: {
+    # 用 transformer 配置项代替，可选值参考配置项文档
+-   type: 'rollup',
+    # 默认值为 dist/cjs，如果想保持原目录，需增加 output 配置项
++   output: 'lib'
+  },
+  umd: {
+    # 改用 externals 代替
+-   globals: {},
+    # 默认值为 dist/umd，如果想保持原目录，需增加 output 配置项
++   output: 'dist'
+  },
+  # 仅 umd 构建支持，改用 umd: { autoprefixer: {} }
+- autoprefixer: {},
+  # 仅 umd 构建支持，改用 umd: { entry: 'xxx' }
+- entry: 'xxx',
+  # 仅 umd 构建支持，改用 umd: { postcssOptions: { plugins: [] } }
+- extraPostCSSPlugins: []
+  # 仅 umd 构建支持，改用 umd: { entry: { 'src/xx': {} } }
+- overridesByEntry: {},
+  # 改用 platform 配置项
+- target: 'node',
+  # 改用 esm/cjs: { overrides: {}, ignores: [] } 实现
+- browserFiles: [],
+- nodeFiles: [],
+  # 仅 umd 构建支持，改用 umd: { externals: {} }
+- externalsExclude: {},
+- extraExternals: {},
+  # 改用 define 配置项
+- inject: {},
+- replace: {},
+});
+```
+
+## 其他功能升级
+
+### test
+
+不再内置，可通过 `father g jest` 生成测试配置。
+
+### precommit
+
+不再内置，未来将通过 `father g lint`、`father g commitlint` 等命令来生成各类提交预检查脚本。
+
+## 升级验证
+
+如果升级前使用的是 babel 模式，那么建议通过对比产物验证升级差异，步骤如下：
+
+1. 从 `node_modules` 将旧版本产物复制到项目中，并使用 `git commit` 命令提交一条临时记录
+2. 使用新配置执行 `father build`，确保产物可以成功构建
+3. 使用 `git diff` 命令对比前后产物差异，产物没有逻辑性差异即验证通过（由于 babel 版本升级，存在 helpers 引入变化是正常的）
+
+如果升级前使用的是 rollup 模式（配置 `umd` 也是基于 rollup 构建），那么建议寻找测试项目验证升级差异，步骤如下：
+
+1. 使用新配置执行 `father build`，确保产物可以成功构建
+2. 参考 [开发 - 在项目中调试](./dev.md#在项目中调试) 进行产物功能验证，功能正常则验证通过
+
+至此，恭喜你完成 father 的升级！
diff --git a/docs/guide/pre-bundle.md b/docs/guide/pre-bundle.md
new file mode 100644
index 00000000..b1eaec23
--- /dev/null
+++ b/docs/guide/pre-bundle.md
@@ -0,0 +1,33 @@
+# 依赖预打包（实验性）
+
+> 注意：依赖预打包**仅适用于 Node.js 项目**，面向 Browser 的项目请勿使用
+
+依赖预打包是指将项目的依赖、以及依赖的依赖，提前编译成项目的产物之一，而项目的源码也改为直接从预打包产物中引入依赖。
+
+这是近年来社区 Node.js 项目流行的依赖处理方式，它可以给我们带来以下优点：
+
+1. **NPM 包发布后安装体积更小、速度更快**。由于 NPM 包的依赖树往往十分复杂，我们依赖的只是 A 这棵树，安装的却可能是一片森林，但却不是每棵树都会被用到。而依赖预打包能将依赖打包成单个文件，让一片森林压缩成一棵大树，再跟随我们的项目一起发布 NPM，达到体积更小、速度更快的目的。
+2. **提升项目稳定性**。相信大家都碰到过『昨天还好好的，今天怎么就挂了』的情况，即便底层依赖的更新再小心翼翼，也无法验证上层项目的所有场景，更何况有些底层依赖发版还不一定遵循 semver 的约定。而依赖预打包可以将『底层依赖更新』这件事由被动变为主动，需要更新的时候我们再重新预打包一份便是，从而大大提升项目稳定性。
+3. **NPM 包发布后安装 0 warning**。由于 NPM 安装会进行 `peerDependencies` 的校验，可能会产生大量的警告，依赖预打包后不需要安装，用户在使用我们的 NPM 包时也不会再看到警告信息了。而我们作为 NPM 包开发者，在开发阶段安装的时候仍然是可以审查这些警告信息的。
+
+但依赖预打包要处理的情况往往比想象中复杂，我们会遇到 `dynamic require/import`，也会遇到相邻产物文件的读取，这都可能使得依赖预打包失败、或者产物不可用。
+
+father 已经尽可能地在处理这些 case，但仍然改变不了它**现阶段只能作为实验性功能**的事实，所以请谨慎在项目中使用依赖预打包能力，也欢迎将遇到的问题反馈到 [issue](https://github.com/umijs/father-next/issues/28) 中、帮助 father 改进。
+
+延伸阅读：[云谦公众号文章：coa 和依赖锁定](https://mp.weixin.qq.com/s/KbmpzvoB1yJlNDEO1p_fJQ)
+
+## 如何构建
+
+只需要使用 `prebundle` 配置项，再执行 `father prebundle` 即可产出依赖预打包产物：
+
+```js
+// .fatherrc.js
+export default {
+  prebundle: {
+    deps: ['pkg-a', 'pkg-b'], // 需要预打包的依赖包名，需要安装在 `devDependencies` 中
+    output: 'compiled', // 默认输出目录，有自定义需求时才需配置
+  },
+};
+```
+
+更多配置项可参考 [配置项](../config.md)。
diff --git a/docs/guide/release.md b/docs/guide/release.md
new file mode 100644
index 00000000..a2b5c11d
--- /dev/null
+++ b/docs/guide/release.md
@@ -0,0 +1,42 @@
+# 发布
+
+通常仅需 4 步即可完成普通 NPM 包发布，monorepo 项目请参考各自 monorepo 方案的发包实践。
+
+## 前置工作
+
+1. 执行 `npm whoami` 查看当前用户是否已经登录，如果未登录则执行 `npm login`
+2. 检查 `package.json` 中的 NPM 包名及 `publishConfig` 是否符合预期
+
+## 更新版本号
+
+使用 `npm version` 命令更新版本号，例如：
+
+```bash
+# 发布一个 patch 版本
+$ npm version patch -m "build: release %s"
+```
+
+该命令将会自动生成 git tag 及 git commit，并将版本号更新到 `package.json` 中。更多用法可参考 NPM 文档：https://docs.npmjs.com/cli/v8/commands/npm-version
+
+## 构建及发布
+
+father 4 的脚手架默认已将 [项目体检命令](./doctor.md) 及构建命令配置到 `prepublishOnly` 脚本中：
+
+```diff
+  "scripts": {
+    ...
++   "prepublishOnly": "father doctor && npm run build"
+  },
+```
+
+所以我们只需要执行发布即可：
+
+```bash
+# NPM 会自动执行 prepublishOnly 脚本然后完成发布
+$ npm publish
+```
+
+## 后置工作
+
+1. **功能验证：**使用测试项目下载新发布的 NPM 包，验证功能是否正常
+2. **更新日志：**将本次发布的变更通过 GitHub 的 Release Page 进行描述，也可以选择在前置工作中将变更描述写入 `CHANGELOG.md` 文件（未来 father 会提供自动化的更新日志生成能力，敬请期待）
diff --git a/docs/guide/umd.md b/docs/guide/umd.md
new file mode 100644
index 00000000..0d617e18
--- /dev/null
+++ b/docs/guide/umd.md
@@ -0,0 +1,26 @@
+# 构建 UMD 产物
+
+## 如何选择
+
+只有在满足如下任意条件的情况下，才需要选择输出 UMD 产物：
+
+1. 项目的用户可能需要将该依赖做 external 处理、并在 HTML 中通过 script 标签直接引入 CDN 上的产物（类似 React 或 antd）
+2. 项目需要产出编译后的样式表给用户使用，例如将 Less 文件以特定的变量编译成 CSS 文件，常见于基于 antd、又需要自定义主题的组件库
+
+## 如何构建
+
+只需要使用 `umd` 配置项，再执行 `father build` 即可产出 UMD 产物：
+
+```js
+// .fatherrc.js
+export default {
+  // 以下为 umd 配置项启用时的默认值，有自定义需求时才需配置
+  umd: {
+    entry: 'src/index', // 默认构建入口文件
+  },
+};
+```
+
+更多配置项可参考 [配置项](../config.md)。
+
+在 father 项目中，UMD 产物以 Bundle 模式进行构建，关于 Bundle 模式的介绍可参考 [构建模式 - Bundle](./build-mode.md#bundle)。