@modern-js/main-doc 2.21.1 → 2.22.1

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

@@ -9,24 +9,26 @@ Modern.js 提供了 `modern gen-release-note` 命令，支持通过当前存在
 默认生成的 Release Note 格式为：
 
 ```markdown
-[[#1220](https://github.com/web-infra-dev/modern.js/pull/1220)] feat: support bff operators -- Ming
+- fix: add missing type definitions by @zllkjc in https://github.com/web-infra-dev/modern.js/pull/3835
 ```
 
 根据 commit 信息获取 changeset 的 Pull Request ID，并生成 Github 的链接，内容为 changeset 的 changelog 信息和作者信息。
 
+:::info
+获取作者信息，需要提供 Github Token 环境变量，通过 GITHUB_AUTH_TOKEN 传入。
+:::
+
 当默认生成 Release Note 逻辑不能满足需求时，支持自定义 Release Note 格式。
 
 ## 信息
 
-### 自定义 Release Note 所需信息
+### getReleaseInfo
 
 生成 Release Note 信息需要先收集一些信息，比如 commit ID、Pull Request ID、commit message 等等。
 
 该逻辑可通过 `getReleaseInfo` 函数实现。
 
-#### getReleaseInfo
-
-##### Params
+#### Params
 
 - commit
 
@@ -34,40 +36,71 @@ Modern.js 提供了 `modern gen-release-note` 命令，支持通过当前存在
 
 当前 changeset 对应的 commit message 信息。
 
-执行 `git log --pretty=format:%h--%s--%an .changeset/${changeset.id}.md` 的结果。
+执行 `git log --pretty=format:%h--%s--%ae .changeset/${changeset.id}.md` 的结果。
 
 - commitObj
 
 初步解析 commit 获取基本信息。
 
 ```ts
+export enum CommitType {
+  Performance = 'performance',
+  Features = 'features',
+  BugFix = 'bugFix',
+  Doc = 'doc',
+  Other = 'other',
+}
+
 interface Commit {
   id: string; // commit id
-  type: 'feature' | 'fix'; // commit 类型，默认通过开头字符串如果为 fix，类型为 fix，其他为 feature
+  type: CommitType;
   repository?: string; // 参数传入的 repo 信息或者 package.json 中定义的 repository 信息
   pullRequestId?: string;
   author?: string;
   message: string; // commit message
   summary: string; // changeset summary
+  summary_zh: string; // changeset zh summary
   [key: string]: string | undefined;
 }
 ```
 
-##### 返回值
+#### 返回值
 
 commitObj， 补充后完整的 commit 对象。
 
-##### 默认实现
+#### 默认实现
 
-Modern.js 的默认实现为：根据 commit 信息拆分出 Pull Request ID 和作者，加入到 commitObj 中。
+Modern.js 的默认实现为：根据 commit 信息拆分出 Pull Request ID，并根据 commit id 获取到用户信息，加入到 commitObj 中。
 
 ```ts
 function getReleaseInfo(commit: string, commitObj: Commit) {
   const commitRegex = /(.*)\(#(\d*)\)/;
 
-  const [, message, author] = commit.split('--');
-
-  commitObj.author = author;
+  const [commitId, message, email] = commit.split('--');
+
+  const author = AuthorMap.get(email);
+  const token = authToken || process.env.GITHUB_AUTH_TOKEN;
+  if (author) {
+    commitObj.author = author;
+  } else if (repo && token) {
+    try {
+      const res = await axios.get(
+        `https://api.github.com/repos/${repo}/commits/${commitId}`,
+        {
+          method: 'GET',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: token,
+          },
+        },
+      );
+      const author = res.data.author.login;
+      commitObj.author = author;
+      AuthorMap.set(email, author);
+    } catch (e) {
+      console.warn(e);
+    }
+  }
 
   if ((message || commitObj.summary).match(commitRegex)) {
     const [, messageShort, pullRequestId] = (
@@ -81,75 +114,56 @@ function getReleaseInfo(commit: string, commitObj: Commit) {
 }
 ```
 
-### 使用获取的信息生成 Release Note
+#### getReleaseNoteLine
 
 根据 `getReleaseInfo` 中获取的 commit 对象信息，生成对应的 Release Note。
 
 该逻辑可通过 `getReleaseNoteLine` 函数实现。
 
-#### getReleaseNoteLine
-
-##### Params
+#### Params
 
 - commit
 
 类型和上述 commitObj 类型一致。
 
-##### 返回值
+- lang
+
+类型： string;
+
+获取对应语言的 Release Note 信息，支持 `en` 和 `zh`，默认为 `en`。
+
+#### 返回值
 
 生成的 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(
+export function getReleaseNoteLine(
   commit: Commit,
-  customReleaseNoteFunction?: CustomReleaseNoteFunction,
+  lang: 'en' | 'zh' = 'en',
 ) {
-  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`;
+  const { repository, pullRequestId, summary, summary_zh, author } = commit;
+  const pullRequest =
+    pullRequestId && repository
+      ? `https://github.com/${repository}/pull/${pullRequestId}`
+      : '';
+  if (lang === 'en') {
+    return `- ${summary}${author ? ` by @${author}` : ''}${
+      pullRequest ? ` in ${pullRequest}` : ''
+    }\n`;
   }
-  return `${formatSummary(summary, pullRequestId)}\n`;
+  return `- ${summary_zh}${author ? ` 由 @${author} 实现` : ''}${
+    pullRequest ? `， 详情可查看 ${pullRequest}` : ''
+  }\n`;
 }
 ```
 
 ## 使用自定义模块
 
-`gen-release-note` 命令支持 `--custom` 参数，该参数可传入自定义 release note 模块的模块名称或者路径。
+`gen-release-note` 命令支持 `--custom` 参数，该参数可传入自定义 Release Note 模块的模块名称或者路径。
 
 ### 配置相对路径
 
@@ -173,10 +187,10 @@ module.exports = {
 执行下面命令：
 
 ```bash
-pnpm run gen-release-note -- --custom ./scripts/my-release-note-config.js
+pnpm run gen-release-note --custom ./scripts/my-release-note-config.js
 ```
 
-也可以把命令参数直接定义到 package.json 中：
+也可以把命令参数直接定义到 `package.json` 中：
 
 ```json title="package.json"
 {
@@ -194,7 +208,7 @@ pnpm run gen-release-note -- --custom ./scripts/my-release-note-config.js
 
 custom 参数值还可以使用模块工程方案进行管理，提供通用方案。
 
-1. 使用 npx @modern-js/create@latest 创建模块工程方案。
+#### 使用 `npx @modern-js/create@latest` 创建模块工程方案
 
 ```md
 ? 请选择你想创建的工程类型：Npm 模块
@@ -203,7 +217,7 @@ custom 参数值还可以使用模块工程方案进行管理，提供通用方
 ? 请选择包管理工具：pnpm
 ```
 
-2. 实现自定义内容。
+#### 实现自定义内容
 
 ```ts title="src/index.ts"
 export function getReleaseInfo() {}
@@ -211,19 +225,19 @@ export function getReleaseInfo() {}
 export function getReleaseNoteLine() {}
 ```
 
-3. 将模块发布到 NPM。
-4. 在目标仓库根目录安装对应模块，例如 `custom-release-note`。
-5. 执行 gen-release-note 命令添加 custom 参数
+#### 将模块发布到 NPM
+#### 在目标仓库根目录安装对应模块，例如 `custom-release-note`
+#### 执行 gen-release-note 命令添加 custom 参数
 
 ```bash
-pnpm run gen-release-note -- --custom custom-release-note
+pnpm run gen-release-note --custom custom-release-note
 ```
 
 ### 使用 Monorepo 工程方案
 
 如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
 
-1. 执行 `pnpm run new` 创建模块子项目
+#### 执行 `pnpm run new` 创建模块子项目
 
 ```md
 ? 请选择你想创建的工程类型：Npm 模块
@@ -232,7 +246,7 @@ pnpm run gen-release-note -- --custom custom-release-note
 ? 请选择开发语言：TS
 ```
 
-2. 实现自定义内容。
+#### 实现自定义内容
 
 ```ts title="src/index.ts"
 export function getReleaseInfo() {}
@@ -240,7 +254,7 @@ export function getReleaseInfo() {}
 export function getReleaseNoteLine() {}
 ```
 
-3. 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-release-note`。
+#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-release-note`。
 
 ```json title="package.json"
 {
@@ -250,10 +264,10 @@ export function getReleaseNoteLine() {}
 }
 ```
 
-4. 执行 `gen-release-note` 命令添加 `--custom` 参数
+#### 执行 `gen-release-note` 命令添加 `--custom` 参数
 
 ```bash
-pnpm run gen-release-note -- --custom custom-release-note
+pnpm run gen-release-note --custom custom-release-note
 ```
 
 该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

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

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

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

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

package/docs/zh/guides/topic-detail/generator/create/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "@modern-js/create",
+  "position": 1
+}

package/docs/zh/guides/topic-detail/generator/create/config.mdx

@@ -0,0 +1,76 @@
+---
+sidebar_position: 3
+---
+
+# 配置参数
+
+`@modern-js/create` 提供了 [--config](/guides/topic-detail/generator/create/option.html#-c,---config-<config>) 参数，用于提前指定执行过程中交互问题的答案。
+
+这里将介绍不同情况下，可以在 `config` 中配置的字段及字段值。
+
+
+## 通用配置
+
+### solution
+
+问题：请选择你想创建的工程类型
+
+选项：
+
+- Web 应用 -- mwa
+
+- Npm 模块 -- module
+
+- 文档站 -- doc
+
+- Monorepo -- monorepo
+
+### scenes
+
+问题：请选择项目场景
+
+选项：
+
+使用自定义生成器插件时的插件关键字列表。
+
+## Web 应用
+
+import LanguageConfig from '@site-docs/components/language-config';
+
+<LanguageConfig />
+
+import PackageManager from '@site-docs/components/package-manager';
+
+<PackageManager />
+
+### buildTools
+
+问题：请选择构建工具
+
+选项：
+
+- webpack -- webpack
+
+- Rspack -- rspack
+
+## Npm 模块
+
+### packageName
+
+问题：请填写项目名称
+
+:::info
+Npm 模块的 `package.json` 的 name 字段值，该配置值为字符串类型。
+:::
+
+<LanguageConfig />
+
+<PackageManager />
+
+## 文档站
+
+<PackageManager />
+
+## Monorepo
+
+<PackageManager />