@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/topic-detail/changesets/github.md

@@ -0,0 +1,168 @@
+---
+sidebar_position: 9
+---
+
+# 使用 Github 相关工具
+
+## BOT
+
+在 Github 上，Changesets 提供了机器人用于检测当前 Pull Request 是否存在 changeset，并提供了 UI 界面添加和修改 changeset。
+
+### 安装
+
+点击进入[链接](https://github.com/apps/changeset-bot)，右上角选择安装，确认即可安装成功。
+
+![安装机器人](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-install-bot.png)
+
+### 配置
+
+安装成功后，即可进入配置页面，根据需求选择应用仓库即可。
+
+![配置机器人](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-config-bot.png)
+
+### 使用
+
+配置完成后，该机器人将会自动 check 每个 Pull Request 是否添加了 changeset，并通过回复的方式给到提示信息。
+
+
+#### 未添加 changeset
+
+![未添加 changeset 状态](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-no-changeset.png)
+
+可在仓库执行 `pnpm run change` 添加 changeset，也可直接点击下方第二个链接填写 changeset。
+
+#### 已添加 changeset
+
+![已添加 changeset 状态](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-exist-changeset.png)
+
+可点击下方链接修改和添加新的 changeset。
+
+#### 不需要 changeset
+
+可直接忽略未添加时的提示信息，它不会造成 Pull Request 不能合并的问题。
+
+## Action
+
+### 自动创建 Release Pull Request
+
+Modern.js 提供了自动创建发版 Pull Request 的 Github Action，提供基于选择的分支自动执行 bump 操作，更新 lock 文件及创建 Pull Request 操作。
+
+### 使用
+
+在仓库中创建 `.github/workflows/release-pull-request.yml` 文件，填入以下内容：
+
+```yaml
+name: Release Pull Request
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release Version(v1.0.0)'
+        required: true
+
+jobs:
+  release:
+    name: Create Release Pull Request
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@master
+        with:
+        # This makes Actions fetch only one branch to release
+          fetch-depth: 100
+
+      - name: Create Release Pull Request
+        uses: modern-js-dev/actions@main
+        with:
+          # this expects you to have a script called release which does a build for your packages and calls changeset publish
+          versionNumber: ${{ github.event.inputs.version }}
+          type: 'pull request'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.ref }}
+
+```
+
+将 Workflow 合并到主分支后，进入 Github 仓库对应的 Action 页面，选择 Release Pull Request：
+
+![Release Pull Request Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/action-pull-request.png)
+
+选择本次发布的分支并填入版本号，版本号格式推荐 v1.0.0，点击 Run workflow 按钮：
+
+![Run Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/run-pull-request-action.png)
+
+workflow 运行完成后将自动创建 `Release-${version}` 的 Pull Request，自动完成 `bump` changeset 相关版本号并更新 lock 文件，Pull Request 的内容为执行 `gen-release-note` 命令自动生成的 Release Note。
+
+![Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-pull-request.png)
+
+### 自动 Release
+
+Modern.js 提供了自动创建发版 Pull Request 的 Github Action，提供基于选择的分支自动执行 release 操作，将包发布到 NPM 上。
+
+
+#### 使用
+
+在仓库中创建 `.github/workflows/release.yml` 文件，填入以下内容：
+
+```yaml
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        type: choice
+        description: 'Release Version(canary, alpha, pre, latest)'
+        required: true
+        default: 'canary'
+        options:
+        - canary
+        - alpha
+        - pre
+        - latest
+      branch:
+        description: 'Release Branch(confirm release branch)'
+        required: true
+        default: 'main'
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@master
+        with:
+        # This makes Actions fetch only one branch to release
+          fetch-depth: 1
+
+      - name: Release
+        uses: modern-js-dev/actions@main
+        with:
+          # this expects you to have a script called release which does a build for your packages and calls changeset publish
+          version: ${{ github.event.inputs.version }}
+          branch: ${{ github.event.inputs.branch }}
+          type: 'release'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.ref }}
+
+```
+
+配置仓库的 NPM_TOKEN:
+
+![配置 Token](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/github-set-npm-token.png)
+
+将 Workflow 合并到主分支后，进入 Github 仓库对应的 Action 页面，选择 Release：
+
+![Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-action.png)
+
+选择分支名称和发布版本类型，点击 Run workflow 按钮：
+
+![Run Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/run-release-workflow.png)
+
+Workflow 将自动完成仓库 build 和发布到 NPM 流程。

package/zh/guides/topic-detail/changesets/introduce.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 1
+---
+
+# 认识 Changesets
+
+Modern.js 默认集成了 [Changesets](https://github.com/changesets/changesets) 用于模块和 Monorepo 工程方案项目中的包版本管理。
+
+## 特点
+
+Changesets 具有以下几个特点：
+
+- 在开发时，需要开发者提供本次变更涉及的包名称、升级版本类型(`pathch`、`minor`、`major`)及变更信息，即 changeset。
+
+- 在发布版本时，会根据 changeset 自动升级对应包的版本号，并在对应的包中生成 Changelog 信息。
+
+- 在 Monorepo 场景中，changeset 会自动生成仓库依赖图，升级时只会升级变更包及相关依赖包的版本号。
+
+## 初始化
+
+Modern.js 默认创建的模块和 Monorepo 工程方案项目已经初始化完成 Changesets，在项目根目录会自动创建 `.changeset` 目录，及 `.changeset/config.json` 的配置文件。
+
+并且，Modern.js 在其对应的工程方案工具 `@modern-js/module-tools` 和 `@modern-js/monorepo-tools` 提供了 Changesets 相应的命令，无需再手动安装 Changesets 相关依赖。
+
+
+Changesets 默认配置如下：
+
+```json title=".changeset/config.json"
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
+```
+
+配置文件提供了生成 Changesets 的一些基本配置，字段详细介绍请参考后续章节： [Changesets 配置文件](/docs/guides/topic-detail/changesets/config)。
+
+## 命令
+
+- `change` 创建一个 changeset，执行完成该命令后会自动在 `.changeset` 目录生成一个 changeset 文件。
+
+- `bump` 根据当前 changeset 升级对应包版本号。
+
+- `pre` 标记进入和退出 `pre release` 模式，在 `pre release` 模式下执行 `bump` 命令，将会生成 `x.x.x-${pre-tag}.x` 的版本号格式。
+
+- `release` 发布包到 NPM。
+
+- `status` 查看当前 changeset 状态。
+
+- `gen-release-note` 根据当前的 chagneset 状态生成 Release Note 信息。
+
+具体命令支持的参数可以查看后续对应章节介绍。

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

@@ -0,0 +1,262 @@
+---
+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 获取基本信息。
+
+```typescript
+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 中。
+
+```typescript
+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 的默认实现为：
+
+```typescript
+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` 文件，定义如下内容：
+
+```typescript 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. 实现自定义内容。
+
+```typescript 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. 实现自定义内容。
+
+```typescript 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.md

@@ -0,0 +1,49 @@
+---
+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` 文件用于记录当时进入预发布模式的一些状态信息，当出现状态信息和当前仓库状态不一致时，可直接删除该文件退出预发布模式。