@modern-js/main-doc 2.51.0 → 2.53.0

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

@@ -1,274 +0,0 @@
----
-sidebar_position: 8
----
-
-# 自定义 Release Note 格式
-
-Modern.js 提供了 `modern gen-release-note` 命令，支持通过当前存在的 changeset 和 git commit 信息自动生成 Release Note 信息，在发布命令执行之前，可以通过执行该命令生成本次发布的 Release Note。
-
-默认生成的 Release Note 格式为：
-
-```markdown
-- 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 格式。
-
-## 信息
-
-### getReleaseInfo
-
-生成 Release Note 信息需要先收集一些信息，比如 commit ID、Pull Request ID、commit message 等等。
-
-该逻辑可通过 `getReleaseInfo` 函数实现。
-
-#### Params
-
-- commit
-
-类型： string;
-
-当前 changeset 对应的 commit message 信息。
-
-执行 `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: 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，并根据 commit id 获取到用户信息，加入到 commitObj 中。
-
-```ts
-function getReleaseInfo(commit: string, commitObj: Commit) {
-  const commitRegex = /(.*)\(#(\d*)\)/;
-
-  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] = (
-      message || commitObj.summary
-    ).match(commitRegex)!;
-    commitObj.pullRequestId = pullRequestId;
-    commitObj.message = messageShort.trim();
-  }
-
-  return commitObj;
-}
-```
-
-#### getReleaseNoteLine
-
-根据 `getReleaseInfo` 中获取的 commit 对象信息，生成对应的 Release Note。
-
-该逻辑可通过 `getReleaseNoteLine` 函数实现。
-
-#### Params
-
-- commit
-
-类型和上述 commitObj 类型一致。
-
-- lang
-
-类型： string;
-
-获取对应语言的 Release Note 信息，支持 `en` 和 `zh`，默认为 `en`。
-
-#### 返回值
-
-生成的 Release Note。
-
-#### 默认实现
-
-Modern.js 的默认实现为：
-
-```ts
-export function getReleaseNoteLine(
-  commit: Commit,
-  lang: 'en' | 'zh' = 'en',
-) {
-  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 `- ${summary_zh}${author ? ` 由 @${author} 实现` : ''}${
-    pullRequest ? `， 详情可查看 ${pullRequest}` : ''
-  }\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` 即可。
-
-### 使用 Modern.js Module
-
-custom 参数值还可以使用 Modern.js Module 进行管理，提供通用方案。
-
-#### 使用 `npx @modern-js/create@latest` 创建 Modern.js Module
-
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写项目名称：custom-release-note
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
-```
-
-#### 实现自定义内容
-
-```ts title="src/index.ts"
-export function getReleaseInfo() {}
-
-export function getReleaseNoteLine() {}
-```
-
-#### 将模块发布到 NPM
-#### 在目标仓库根目录安装对应模块，例如 `custom-release-note`
-#### 执行 gen-release-note 命令添加 custom 参数
-
-```bash
-pnpm run gen-release-note --custom custom-release-note
-```
-
-### 使用 Monorepo 工程方案
-
-如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
-
-#### 执行 `pnpm run new` 创建模块子项目
-
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写子项目名称：custom-release-note
-? 请填写子项目目录名称：custom-release-note
-? 请选择开发语言：TS
-```
-
-#### 实现自定义内容
-
-```ts title="src/index.ts"
-export function getReleaseInfo() {}
-
-export function getReleaseNoteLine() {}
-```
-
-#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-release-note`。
-
-```json title="package.json"
-{
-  "devDependencies": {
-    "custom-release-note": "workspace:*",
-    ...
-  }
-}
-```
-
-#### 执行 `gen-release-note` 命令添加 `--custom` 参数
-
-```bash
-pnpm run gen-release-note --custom custom-release-note
-```
-
-该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

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

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

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

@@ -1,231 +0,0 @@
----
-sidebar_position: 3
----
-
-# 发布正式版本
-
-发版正式版本时，我们需要根据开发过程中生成的 changesets 进行相关包版本号升级，并执行 publish 命令发布到 NPM 上。
-
-## 步骤
-
-:::info
-以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
-
-:::
-
-### Modern.js Module
-
-#### 在根目录执行 bump 命令
-
-```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 工程方案
-
-#### 在根目录执行 bump 命令
-
-```bash
-pnpm run bump
-```
-
-![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
-
-执行该命令时，changesets 会自动进行以下操作：
-
-- 删除 `.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，使用 `release` 命令在发布时将会自动去除 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` 发布包。
-
-```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/docs/zh/guides/topic-detail/model/test-model.mdx

@@ -1,45 +0,0 @@
----
-sidebar_position: 9
-title: 测试 Model
----
-# 测试 Model
-
-好的测试对代码的稳健性至关重要。下面以 [快速上手](/guides/topic-detail/model/quick-start) 的 `countModel` 为例，演示在 Modern.js 中，如何对 Model 进行单元测试。
-
-使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「单元测试 / 集成测试」功能
-```
-
-即可开启测试功能支持。
-
-新增 `count.test.ts` 文件，代码如下：
-
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import countModel from './count';
-
-describe('test model', () => {
-  it('count value should plus one after add', () => {
-    const store = createStore();
-    const [state, { add }] = store.use(countModel);
-
-    expect(state).toEqual({ value: 1 });
-
-    add();
-
-    expect(store.use(countModel)[0]).toEqual({ value: 2 });
-  });
-});
-```
-
-:::info
-这里使用的 [`createStore`](/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/configure/app/runtime/state) 的配置去创建 `store`。
-
-:::
-
-在测试用例里，我们新建一个 `store` 来挂载 `countModel`，通过 `store.use` 获取 `countModel` 的 State 和 Actions。然后调用 `add` Action 更新状态，并断言更新后的状态值。
-
-执行 `pnpm run test` 命令，触发测试用例的执行。

package/docs/zh/guides/topic-detail/monorepo/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Monorepo",
-  "position": 4
-}

package/docs/zh/guides/topic-detail/monorepo/create-sub-project.mdx

@@ -1,53 +0,0 @@
----
-sidebar_position: 2
----
-
-# 创建子项目
-
-本章将要介绍如何在 Monorepo 工程下创建子项目。
-
-> Modern.js 支持使用 pnpm 和 Yarn 的 Monorepo，这里以使用 pnpm 为例。以下命令可以以同样方式使用 Yarn 来执行。
-
-Modern.js 针对 Monorepo 工程提供了生成器功能，它用于在 Monorepo 工程下创建不同类型的 Monorepo 子项目。在生成器中提供以下类型子项目的创建：
-
-- 「应用」类型
-- 「模块」类型
-
-要启动 Monorepo 的生成器功能，可以在 Monorepo 工程根目录下执行命令：
-
-```
-pnpm run new
-```
-
-:::info 补充信息
-使用 Yarn 的方式：`yarn new`
-
-:::
-
-执行成功后，可以看到如下内容：
-
-```
-? 请选择你想创建的工程类型 (Use arrow keys)
-❯ Web 应用
-  Npm 模块
-```
-
-然后根据不同的需求选择对应的类型项目选项，选择之后便开始出现对应子项目类型的问题和选项。例如选择「应用」后会出现：
-
-```
-? 请选择你想创建的工程类型：Web应用
-? 请填写子项目名称
-```
-
-当完成所有生成器问题之后，便开始进行项目的创建和项目依赖的下载。当创建成功之后，可以看到类似以下内容：
-
-```
-[INFO] 依赖自动安装成功
-[INFO] 创建成功！
-可在新项目的目录下运行以下命令：
-pnpm run dev          # 启动开发服务器
-pnpm run build        # 构建生产环境产物
-pnpm run serve        # 启动生产环境服务
-pnpm run lint         # 运行 ESLint 并自动修复问题
-pnpm run new          # 启用可选功能或创建项目要素
-```

package/docs/zh/guides/topic-detail/monorepo/intro.mdx

@@ -1,14 +0,0 @@
----
-sidebar_position: 1
----
-
-# Monorepo 工程介绍
-
-Modern.js 提供了对于 Monorepo 工程方案的支持，其主要通过 `@modern-js/monorepo-tools` 来提供功能。
-
-该专题将从以下方面来讲解如何使用 Modern.js 对 Monorepo 进行管理：
-
-- 在 Monorepo 中创建子项目
-- Monorepo 下子项目之间的联调开发
-- 发布 Monorepo 的子项目
-- 部署 Monorepo 子项目