npm - @modern-js/main-doc - Versions diffs - 2.52.0 → 2.54.0 - Mend

@modern-js/main-doc 2.52.0 → 2.54.0

Files changed (77) hide show

package/docs/zh/guides/topic-detail/changesets/config.mdx DELETED Viewed

@@ -1,147 +0,0 @@
----
-sidebar_position: 5
----
-# Changesets 配置文件
-我们前面了解到，初始化 Modern.js 仓库时，会默认初始化 changesets 的配置文件，即 `.changeset/config.json` 文件，下面我们将详细了解一下该文件中支持哪些配置。
-## 配置介绍
-### commit
-类型： `boolean`
-默认值： `false`
-当配置该字段为 `true` 时，在执行 `change` 和 `bump` 命令时，将自动执行提交代码操作。
-默认的 commit 信息格式如下：
-![change commit](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-change-commit-info.png)
-![bump commit](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bump-commit-info.png)
-该 commit 信息支持自定义，我们将在[自定义提交 commit 信息](/guides/topic-detail/changesets/commit)章节进行详细介绍。
-### access
-类型：`restricted` | `public`
-默认值：`restricted`
-用于配置当前包的发布形式，如果配置为 `restricted`，将作为私有包发布，如果为 `public`，则发布公共范围包。
-对于仓库中存在部分包需要配置 access，可以在 `package.json` 中配置 `publishConfig`，例如：
-```json title=package.json
-{
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  }
-}
-```
-对于不需要发布的包，可以在 `package.json` 中设置 `private` 为 `true`，阻止其进行发布。
-### baseBranch
-类型： `string`
-默认值： `main`
-仓库主分支。该配置用于计算当前分支的变更包并进行分类。
-### ignore
-类型：`string[]`
-默认值：`[]`
-用于声明执行 `bump` 命令时忽略的包，和 `bump` 命令的 `--ignore` 参数用法一致，注意两者不能同时使用。
-### fixed
-类型： `string[][]`
-默认值：`[]`
-用于 monorepo 中对包进行分组，相同分组中的包版本号将进行绑定，每次执行 `bump` 命令时，同一分组中的包只要有一个升级版本号，其他会一起升级。
-支持使用正则匹配包名称。
-### linked
-类型： `string[][]`
-默认值：`[]`
-和 `fixed` 类似，也是对 monorepo 中对包进行分组，但是每次执行 `bump` 命令时，只有和 changeset 声明的变更相关的包才会升级版本号，同一分组的变更包的版本号将保持一致。
-支持使用正则匹配包名称。
-### updateInternalDependencies
-类型：`patch` | `minor`
-默认值：`patch`
-用于声明更新内部依赖的版本号规则。
-当执行 `bump` 命令升级版本号时，默认会自动更新仓库中使用该包的依赖声明。配置该字段为 `minor` 后，如果升级版本号为 `patch` 类型，将不会自动更新引用依赖声明。
-例如：
-```
-pkg-a @ version 1.0.0
-pkg-b @ version 1.0.0
-  depends on pkg-a at range `^1.0.0
-```
-默认情况下，升级 `pkg-a` 至 `1.0.1` 时，会更新 `pkg-b` 中的 `pkg-a` 的依赖版本为 `^1.0.1`。
-当配置 `updateInternalDependencies` 为 `minor` 时，升级 `pkg-a` 至 `1.0.1` 时，`pkg-b` 中的 `pkg-a` 的依赖版本将不会更新，只有 `pkg-a` 升级版本号为 `1.1.0` 或者 `2.0.0` 时，才会更新 `pkg-b` 中的 `pkg-a` 的依赖。
-### changelog
-类型：`boolean` | `string` | `[string, unknow]`
-默认值：`@changesets/cli/changelog`
-生成 changelog 规则。
-配置为 `false` 时，执行 bump 命令时，在 `CHANGELOG.md` 文件中只声明版本号，不声明其他 changelog 信息。
-![关闭 changelog 配置](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-empty-changelog.png)
-配置为 `@changesets/cli/changelog` 将使用官方提供的 changlog 生成规则，将 changeset 信息转换为 changlog 内容。
-配置为数组时，第一个参数为自定义 NPM 包或者路径，第二个参数为需要传入的默认参数配置，自定义格式我们将在后续[自定义 changelog](/guides/topic-detail/changesets/changelog) 章节讲解。
-### \_\_\_experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH
-一些实验性配置。
-#### onlyUpdatePeerDependentsWhenOutOfRange
-类型：`boolean`
-默认值：`false`
-针对于 `peerDependence` 依赖的升级策略配置，默认针对 `peerDependence` 在 `minor` 和 `major` 版本升级时，当前包会升级大版本。
-该配置设置为 true 时，仅当 `peerDependence` 声明包依赖超出声明范围时才更新版本。
-#### updateInternalDependents
-类型： `always` | `out-of-range`
-默认值：`always`
-当执行 `bump` 命令升级版本号时，默认会自动更新仓库中使用该包的依赖声明。当设置该参数为 `out-of-range` 时，只有当依赖声明超出范围时才会更新仓库中使用该包的依赖声明。
-#### useCalculatedVersionForSnapshots
-类型：`boolean`
-默认值：`false`
-使用快照发布时，默认会使用 `0.0.0-timestamp` 的版本格式，保证用户可以正常使用预发布版本。当你需要忽略上述问题，使用正常的版本号格式时，即当前版本为 `1.0.1` 快照版本期望使用`1.0.1-timestamp`，可配置该参数为 `true`。

package/docs/zh/guides/topic-detail/changesets/github.mdx DELETED Viewed

@@ -1,175 +0,0 @@
----
-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:
-        type: choice
-        description: 'Release Type(canary, beta, alpha, latest)'
-        required: true
-        default: 'latest'
-        options:
-        - canary
-        - beta
-        - alpha
-        - latest
-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
-      - ... # install dependencies and build repo package
-      - name: Create Release Pull Request
-        uses: web-infra-dev/actions@v2
-        with:
-          version: ${{ github.event.inputs.version }}
-          versionNumber: 'auto'
-          type: 'pull request'
-          tools: 'modern'
-        env:
-          GITHUB_TOKEN: ${{ secrets.REPO_SCOPED_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_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)
-- 选择本次发布类型，点击 Run workflow 按钮：
-![Run Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/action-pull-request.jpeg)
-- 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.jpeg)
-### 自动 Release
-Modern.js 提供了自动发布版本 的 Github Action，提供基于选择的分支自动执行 release 操作，将包发布到 NPM 上。
-#### 使用
-- 在仓库中创建 `.github/workflows/release.yml` 文件，填入以下内容：
-```yaml
-name: Release
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        type: choice
-        description: 'Release Version(canary, beta, alpha, latest)'
-        required: true
-        default: 'next'
-        options:
-        - canary
-        - beta
-        - alpha
-        - 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
-      - ... # install dependencies and build repo package
-      - name: Release
-        uses: web-infra-dev/actions@v2
-        with:
-          version: ${{ github.event.inputs.version }}
-          branch: ${{ github.event.inputs.branch }}
-          type: 'release'
-          tools: 'modern'
-        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/docs/zh/guides/topic-detail/changesets/introduce.mdx DELETED Viewed

@@ -1,56 +0,0 @@
----
-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 配置文件](/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/docs/zh/guides/topic-detail/changesets/release-note.mdx DELETED Viewed

@@ -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 DELETED Viewed

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