@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/guides/topic-detail/changesets/release-note.mdx

@@ -0,0 +1,259 @@
+---
+sidebar_position: 8
+---
+
+# 自定义 Release Note 格式
+
+Modern.js 提供了 `modern gen-release-note` 命令，支持通过当前存在的 changeset 和 git commit 信息自动生成 Release Note 信息，在发布命令执行之前，可以通过执行该命令生成本次发布的 Release Note。
+
+默认生成的 Release Note 格式为：
+
+```markdown
+[[#1220](https://github.com/modern-js-dev/modern.js/pull/1220)] feat: support bff operators -- Ming
+```
+
+根据 commit 信息获取 changeset 的 Pull Request ID，并生成 Github 的链接，内容为 changeset 的 changelog 信息和作者信息。
+
+当默认生成 Release Note 逻辑不能满足需求时，支持自定义 Release Note 格式。
+
+## 信息
+
+### 自定义 Release Note 所需信息
+
+生成 Release Note 信息需要先收集一些信息，比如 commit ID、Pull Request ID、commit message 等等。
+
+该逻辑可通过 `getReleaseInfo` 函数实现。
+
+#### getReleaseInfo
+
+##### Params
+
+- commit
+
+类型： string;
+
+当前 changeset 对应的 commit message 信息。
+
+执行 `git log --pretty=format:%h--%s--%an .changeset/${changeset.id}.md` 的结果。
+
+- commitObj
+
+初步解析 commit 获取基本信息。
+
+```ts
+interface Commit {
+  id: string; // commit id
+  type: 'feature' | 'fix'; // commit 类型，默认通过开头字符串如果为 fix，类型为 fix，其他为 feature
+  repository?: string; // 参数传入的 repo 信息或者 package.json 中定义的 repository 信息
+  pullRequestId?: string;
+  author?: string;
+  message: string; // commit message
+  summary: string; // changeset summary
+  [key: string]: string | undefined;
+}
+```
+
+##### 返回值
+
+commitObj， 补充后完整的 commit 对象。
+
+##### 默认实现
+
+Modern.js 的默认实现为：根据 commit 信息拆分出 Pull Request ID 和作者，加入到 commitObj 中。
+
+```ts
+function getReleaseInfo(commit: string, commitObj: Commit) {
+  const commitRegex = /(.*)\(#(\d*)\)/;
+
+  const [, message, author] = commit.split('--');
+
+  commitObj.author = author;
+
+  if ((message || commitObj.summary).match(commitRegex)) {
+    const [, messageShort, pullRequestId] = (
+      message || commitObj.summary
+    ).match(commitRegex)!;
+    commitObj.pullRequestId = pullRequestId;
+    commitObj.message = messageShort.trim();
+  }
+
+  return commitObj;
+}
+```
+
+### 使用获取的信息生成 Release Note
+
+根据 `getReleaseInfo` 中获取的 commit 对象信息，生成对应的 Release Note。
+
+该逻辑可通过 `getReleaseNoteLine` 函数实现。
+
+#### getReleaseNoteLine
+
+##### Params
+
+- commit
+
+类型和上述 commitObj 类型一致。
+
+##### 返回值
+
+生成的 Release Note。
+
+##### 默认实现
+
+Modern.js 的默认实现为：
+
+```ts
+function formatSummary(summary: string, pullRequestId?: string) {
+  const [firstLine, ...futureLines] = summary
+    .split('\n')
+    .map(l => l.trimRight());
+
+  let returnVal = firstLine;
+
+  if (futureLines.length > 0) {
+    if (pullRequestId) {
+      returnVal = `\n\n  ${returnVal}`;
+    } else {
+      returnVal = `\n  ${returnVal}`;
+    }
+    returnVal += `\n\n  ${futureLines
+      .filter(l => Boolean(l))
+      .map(l => l)
+      .join('\n\n')}`;
+  }
+  return returnVal;
+}
+
+export async function getReleaseNoteLine(
+  commit: Commit,
+  customReleaseNoteFunction?: CustomReleaseNoteFunction,
+) {
+  if (customReleaseNoteFunction?.getReleaseNoteLine) {
+    return customReleaseNoteFunction.getReleaseNoteLine(commit);
+  }
+
+  const { repository, pullRequestId, summary } = commit;
+  if (pullRequestId && repository) {
+    return `- [#${pullRequestId}](https://github.com/${repository}/pull/${pullRequestId}) ${formatSummary(
+      summary,
+      pullRequestId,
+    )}\n`;
+  }
+  if (pullRequestId) {
+    return `#${pullRequestId} ${formatSummary(summary, pullRequestId)}\n`;
+  }
+  return `${formatSummary(summary, pullRequestId)}\n`;
+}
+```
+
+## 使用自定义模块
+
+`gen-release-note` 命令支持 `--custom` 参数，该参数可传入自定义 release note 模块的模块名称或者路径。
+
+### 配置相对路径
+
+custom 参数值如果为相对路径为**项目跟目录**。
+
+例如创建 `scripts/my-release-note-config.js` 文件，定义如下内容：
+
+```ts title="scripts/my-release-note-config.js"
+function getReleaseInfo(commit, commitObj) {
+  return commitObj;
+}
+
+function getReleaseNoteLine(commit) {}
+
+module.exports = {
+  getReleaseInfo,
+  getReleaseNoteLine,
+};
+```
+
+执行下面命令：
+
+```bash
+pnpm run gen-release-note -- --custom ./scripts/my-release-note-config.js
+```
+
+也可以把命令参数直接定义到 package.json 中：
+
+```json title="package.json"
+{
+    "scripts": {
+        ...
+        "gen-release-note": "modern gen-release-note --custom ./scripts/my-release-note-config.js"
+    },
+    ...
+}
+```
+
+直接执行命令 `pnpm run gen-release-note` 即可。
+
+### 使用模块工程方案
+
+custom 参数值还可以使用模块工程方案进行管理，提供通用方案。
+
+1. 使用 npx @modern-js/create 创建模块工程方案。
+
+```md
+? 请选择你想创建的工程类型 模块
+? 请填写项目名称 custom-release-note
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+2. 实现自定义内容。
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+3. 将模块发布到 NPM。
+4. 在目标仓库根目录安装对应模块，例如 `custom-release-note`。
+5. 执行 gen-release-note 命令添加 custom 参数
+
+```bash
+pnpm run gen-release-note -- --custom custom-release-note
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+1. 执行 `pnpm run new` 创建模块子项目
+
+```md
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 custom-release-note
+? 请填写子项目目录名称 custom-release-note
+? 请选择开发语言 TS
+```
+
+2. 实现自定义内容。
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+3. 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-release-note`。
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-release-note": "workspace: *",
+    ...
+}
+```
+
+4. 执行 `gen-release-note` 命令添加 `--custom` 参数
+
+```bash
+pnpm run gen-release-note -- --custom custom-release-note
+```
+
+该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

package/zh/guides/topic-detail/changesets/release-pre.mdx

@@ -0,0 +1,50 @@
+---
+sidebar_position: 4
+---
+
+# 发布预发布版本
+
+在发布正式版本之前，我们也需要发布预发布版本供内部测试和用户使用，Changesets 也支持发布预发布版本。
+
+## 步骤
+
+:::info
+以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
+
+:::
+
+#### 执行以下命令升级预发布版本版本号：
+
+```bash
+pnpm run bump -- --canary --preid <preid>
+```
+
+`preid` 为预发布版本标记，例如 `alpha`、`beta` 等，默认值为 `next`。
+
+使用 `--canary` 参数后，`bump` 命令由以下三个步骤完成：
+
+- `changeset pre enter <preid>` 进入预发布模式
+
+- `changeset version` 升级版本号
+
+- `changeset pre exit` 退出预发布模式
+
+#### 检查相关变更并提交
+
+检查相关版本号变更是否正确，并提交变更。
+
+建议预发布操作不在主分支上进行，不合入主分支，当预发布验证完成后，直接基于主分支发布正式版本。
+
+#### 执行以下命令发布预发布版本：
+
+```bash
+pnpm run release -- --tag <tag>
+```
+
+发布预发布版本一定要使用 `--tag` 参数，参数值最好和 `preid` 值相同，方便用户使用。
+
+## 注意事项
+
+### 退出预发布模式
+
+在进入预发布模式后，Changesets 会自动在 `.changeset` 目录创建 `pre.json` 文件用于记录当时进入预发布模式的一些状态信息，当出现状态信息和当前仓库状态不一致时，可直接删除该文件退出预发布模式。

package/zh/guides/topic-detail/changesets/release.mdx

@@ -0,0 +1,231 @@
+---
+sidebar_position: 3
+---
+
+# 发布正式版本
+
+发版正式版本时，我们需要根据开发过程中生成的 changeset 进行相关包版本号升级，并执行 publish 命令发布到 NPM 上。
+
+## 步骤
+
+:::info
+以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
+
+:::
+
+### 模块工程方案
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run bump
+```
+
+![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-bump.png)
+
+执行该命令时，changeset 会自动进行以下操作：
+
+- 删除 `.changesets` 目录下的所有 changeset 文件。
+
+- 根据 changeset 信息升级该包版本号。
+
+- 在根目录的 `CHANGELOG.md` 文件中写入 Changelog 信息，文件不存在时会自动创建。
+
+#### 确认并提交当前变更：
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### 在根目录执行以下命令发布包至 NPM：
+
+```bash
+pnpm run release
+```
+
+![执行 release 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-release.png)
+
+#### push 对应的 tag 信息至远程仓库：
+
+```bash
+git push --follow-tags
+```
+
+### Monorepo 工程方案
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run bump
+```
+
+![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
+
+执行该命令时，changeset 会自动进行以下操作：
+
+- 删除 `.changesets` 目录下的所有 changeset 文件。
+
+- 根据 changeset 信息升级相关包的版本号，除了显示写入 changeset 的包，执行命令时还会将 Monorepo 中所有的包进行依赖关系分析，如果需要升级，也会对应的自动升级版本号。
+
+- 在需要升级的包目录的 `CHANGELOG.md` 文件中写入 Changelog 信息，文件不存在时会自动创建。
+
+#### 确认并提交当前变更：
+
+:::info
+需确认自动升级的版本号是否符合预期，如果需要了解版本升级策略，请查看[升级版本策略](/guides/topic-detail/changesets/release#升级版本策略)。
+
+:::
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### 在根目录执行以下命令发布包至 NPM：
+
+```bash
+pnpm run release
+```
+
+执行该命令时，将会依次判断 Monorepo 中所有的 packages 的版本是否在 NPM 中存在，如果不存在将会执行 `publish` 命令发布。
+
+:::warning
+当 Monorepo 中包之间依赖关系使用 workspace 声明时，注意不要直接在 package 对应的子目录直接执行 `npm publish` 发布 package，使用 `relesae` 命令在发布时将会自动去除 workspace 声明，确保 NPM 包发布之后可用。
+
+:::
+
+#### push 对应的 tag 信息至远程仓库：
+
+```bash
+git push --follow-tags
+```
+
+## 参数
+
+### bump 命令参数
+
+- `--snapshot` 生成基于时间戳的版本号。
+
+```bash
+pnpm run bump -- --snapshot canary
+```
+
+执行完成后，对应的升级版本号将会变成 `0.0.0-canary-20220622092823` 的形式，其中 canary 为 snapshot 配置的标记，如果不配置，将直接生成 `0.0.0-20220622092823` 的形式。
+
+该参数主要用于发布临时测试版本进行测试，不需要进行代码提交。
+
+- `--ignore` 发布时手动忽略部分包。
+
+例如本次发布你需要忽略 `module-2` 包：
+
+```bash
+pnpm run bump -- --ignore module-2
+```
+
+命令执行完成后，将会忽略 `module-2` 包的更新。注意如果存在包依赖 `module-2`，需要将对应包也加入到 `ignore` 参数中，否则 `bump` 命令将执行失败。
+
+加入多个包的使用姿势为：
+
+```bash
+pnpm run bump -- --ignore module-2 --ignore module-3
+```
+
+### release 命令参数
+
+- `--otp` 使用 `npm token` 执行 relesae 命令发布对应包
+
+```bash
+pnpm run relese -- --otp <token>
+```
+
+- `--tag` 本地发布使用特定的 tag，默认使用 `latest`
+
+```bash
+pnpm run release -- --tag <tag>
+```
+
+- `--ignore-scripts` 发布时忽略 npm scripts。
+
+执行 `publish` 命令时，npm 会自动触发很多命令，比如 `prepare`、`prepublish`，使用该参数可以忽略这些命令执行。该参数仅支持在使用 pnpm 的 Monorepo 中使用。
+
+```bash
+pnpm run release -- --ignore-scripts
+```
+
+- `--no-git-checks` 发布时忽略检查当前分支。
+
+执行发布命令时，默认会自动检查当前分支是否为发布分支，是否存在未提交变更等等，使用该参数可以忽略 git 相关检查。
+
+```bash
+pnpm run release -- --no-git-checks
+```
+
+## 升级版本策略
+
+### dependencies 或者 devDependencies 依赖
+
+#### patch 版本依赖只升级自身
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `dependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 `patch` 版本升级。
+
+执行 bump 命令后将只会升级 `module-1` 的 patch 版本号。
+
+#### major / minor 版本自身升级 major 或者 minor 版本号，依赖包升级 patch 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 dependencies 中存在`module-1`。
+
+当前存在的 changeset 为 `module-1` 的 minor 版本升级。
+
+执行 bump 命令后 `module-1` 会升级 `minor` 版本号，`module -2` 会升级 `patch` 版本号。
+
+### peerDependencies 依赖
+
+#### patch 版本依赖自身和依赖包都升级 patch 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 patch 版本升级。
+
+执行 bump 命令后将 `module-1` 和 `module-2` 都升级 patch 版本号。
+
+#### major / minor 版本自身升级 major 或者 minor 版本号，依赖包升级 major 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 `minor` 版本升级。
+
+执行 bump 命令后将 module-1 将升级 `minor` 版本号， `module-2` 升级 `major` 版本号。
+
+#### 修改 peerDependencies 的升级策略
+
+`peerDependencies` 的升级策略支持通过配置 `onlyUpdatePeerDependentsWhenOutOfRange` 来修改依赖升级策略，当只有超出声明的版本类型范围时，才对应升级 `peerDependencies`。
+
+```json
+{
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  },
+  ...
+}
+```
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`，声明 `module-1` 的版本号使用 `^`。
+
+当前存在的 changeset 为 `module-1` 的 `patch` 或者 `minor` 版本升级。
+
+执行 `bump` 命令后只升级 `module-1` 版本号。
+
+需注意，如果包版本号在 `0.x.x` 的范围时，`minor` 版本号升级也是超出声明的版本类型范围的。

package/zh/guides/topic-detail/framework-plugin/extend.mdx

@@ -0,0 +1,163 @@
+---
+title: 扩展插件 Hook
+sidebar_position: 5
+---
+# 扩展插件 Hook
+
+本小节介绍如何通过动态注册 [Hook 模型](/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
+
+## 示例
+
+这里我们用一个简单的例子演示一下。假设我们要添加一些管理控制台输出信息的 Hook。
+
+首先我们初始化一个空的项目文件，并添加基础依赖：
+
+```bash
+$ npx @modern-js/create modern-js-demo
+```
+
+### 创建 Hook
+
+我们先创建一个 Hook 模型：
+
+```ts title=config/plugin/myPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+
+const message = createWaterfall<string[]>();
+```
+
+然后注册它：
+
+```ts title=config/plugin/myPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+});
+```
+
+添加 Hook 类型：
+
+```ts title=config/plugin/myPlugin.ts
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+### 使用 Hook
+
+创建插件，通过 `commands` Hook 函数，添加命令处理逻辑：
+
+```ts title=config/plugin/myPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+```
+
+最后 `config/plugin/myPlugin.ts` 的状态是：
+
+```ts title=config/plugin/myPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+import type { CliPlugin } from '@modern-js/core';
+
+const message = createWaterfall<string[]>();
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+然后在 `modern.config.ts` 中添加这个插件：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import myPlugin from './config/plugin/myPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就会执行相关逻辑，但由于没有收集到任何信息，所以控制台输出为空。
+
+那这里我们添加一个：
+
+```ts title=config/plugin/otherPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'other-plugin',
+
+  setup(api) {
+    return {
+      message(list) {
+        return [...list, '[foo] line 0', '[foo] line 1'];
+      },
+    };
+  },
+});
+```
+
+将它添加到配置中：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import myPlugin from './config/plugin/myPlugin';
+import otherPlugin from './config/plugin/otherPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin(), otherPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就可以在控制台看到信息了：
+
+```bash
+$ modern message
+[foo] line 0
+[foo] line 1
+```
+
+以上面这种方式就可以扩展出拥有各种能力的插件 Hook。