npm - @modern-js/main-doc - Versions diffs - 2.51.0 → 2.53.0 - Mend

@modern-js/main-doc 2.51.0 → 2.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (68) hide show

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

@@ -1,269 +0,0 @@
----
-sidebar_position: 7
----
-# 自定义提交 commit 信息
-Changesets 支持配置 `commit` 为 true 时，在执行 `change` 和 `bump` 命令时自动提交当前变更。
-默认的 `commit` 信息由 `@changesets/cli/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 信息。
-## 自定义 commit 信息内容
-commit 信息分为两种：
-- 执行 `change` 命令时自动生成的 commit 信息。
-- 执行 `bump` 命令时自动生成的 commit 信息。
-自定义逻辑主要实现两个函数，`getAddMessage` 和 `getVersionMessage`，分别用来定义上述这两种信息。
-### getAddMessage
-#### Params
-- changeset
-当前创建的 chagneset 信息
-```ts
-type Release = {
-  name: string;
-  type: VersionType;
-};
-type Changeset = {
-  summary: string;
-  releases: Array<Release>;
-};
-```
-- options
-配置 commit 时的配置信息。
-> commit 配置为数组时，第二个参数支持传入默认的配置信息，会对应的使用该参数传递。
-#### 返回值
-commit 信息内容。
-#### 默认实现
-`@changesets/cli/commit` 默认处理逻辑为以 `docs(changeset):` 开头，commit 信息为 changeset 的 `summary`，并根据传入的 `skipCI` 参数配置添加 [skip ci] 信息。
-```ts
-type SkipCI = boolean | 'add' | 'version';
-const getAddMessage = async (
-  changeset: Changeset,
-  options: { skipCI?: SkipCI } | null,
-) => {
-  const skipCI = options?.skipCI === 'add' || options?.skipCI === true;
-  return outdent`docs(changeset): ${changeset.summary}${
-    skipCI ? `\n\n[skip ci]\n` : ''
-  }`;
-};
-```
-> [outdent](https://www.npmjs.com/package/outdent) 目的是删除模板字符串开头的空格内容，使 commit 信息更符合规范。
-### getVersionMessage
-#### Params
-- releasePlan
-```ts
-type VersionType = 'major' | 'minor' | 'patch' | 'none';
-type Release = {
-  name: string;
-  type: VersionType;
-};
-type Changeset = {
-  id: string;
-  summary: string;
-  releases: Array<Release>;
-};
-type ComprehensiveRelease = {
-  name: string;
-  type: VersionType;
-  oldVersion: string;
-  newVersion: string;
-  changesets: string[];
-};
-type PreState = {
-  mode: 'pre' | 'exit'; // pre 模式当前状态
-  tag: string; // pre 的类型
-  initialVersions: {
-    [pkgName: string]: string; // 版本升级前包名及版本号信息，Map 格式
-  };
-  changesets: string[]; // 本次升级的 changeset id 列表
-};
-type ReleasePlan = {
-  changesets: Changeset[]; // 本次升级的 changeset 列表
-  releases: ComprehensiveRelease[]; // 当前升级的包信息，包含包名称、当前版本、升级后版本、升级类型等
-  preState: PreState | undefined; // 当前如果为 pre 发布，提供相关状态信息
-};
-```
-- options
-配置 commit 时的其他参数。
-> commit 配置为数组时，第二个参数支持传入默认的配置信息，会对应的使用该参数传递。
-#### 返回值
-commit 信息内容。
-#### 默认实现
-`@changesets/cli/commit` 默认处理逻辑为：先展示当前需要 release 的包数量，再展示 release 包的名称及新版本号，并根据传入的 `skipCI` 参数配置添加 [skip ci] 信息。
-```ts
-const getVersionMessage = async (
-  releasePlan: ReleasePlan,
-  options: { skipCI?: SkipCI } | null,
-) => {
-  const skipCI = options?.skipCI === 'version' || options?.skipCI === true;
-  const publishableReleases = releasePlan.releases.filter(
-    release => release.type !== 'none',
-  );
-  const numPackagesReleased = publishableReleases.length;
-  const releasesLines = publishableReleases
-    .map(release => `  ${release.name}@${release.newVersion}`)
-    .join('\n');
-  return outdent`
-    RELEASING: Releasing ${numPackagesReleased} package(s)
-    Releases:
-    ${releasesLines}
-    ${skipCI ? `\n[skip ci]\n` : ''}
-`;
-};
-```
-## 配置
-Changesets 配置文件中 `commit` 字段，该字段用于标记是否需要在 `change` 和 `bump` 命令是提交 commit 信息及 commit 信息的获取途径。
-该配置可以为 `boolean`，为 true 时使用默认 `@changesets/cli/commit` 格式化 commit 信息。
-该配置可以为字符串，直接声明获取 commit 信息模块的模块名称或者路径。
-该配置还支持配置数组，数组中第一个元素为获取 commit 信息模块的模块名称或者路径，第二个元素为传入对应函数的参数值，会作为 `getAddMessage` 和 `getVersionMessage` 函数的第二个参数传入。
-### 配置相对路径
-commit 配置如果为相对路径为 `.changesets` 目录下的相对路径。
-例如创建 `.changeset/my-commit-config.js` 文件，定义如下内容：
-```js title=".changeset/my-commit-config.js"
-async function getAddMessage(changeset, options) {}
-async function getVersionMessage(releasePlan, options) {}
-module.exports = {
-  getAddMessage,
-  getVersionMessage,
-};
-```
-commit 配置为 ./my-commit-config.js 即可:
-```json title=".changesets/config.json"
-{
-  "changelog": "./my-commit-config.js",
-   ...
-}
-```
-### 使用 Modern.js Module
-自定义 commit 还可以使用 Modern.js Module 进行管理，提供通用方案。
-#### 使用 `npx @modern-js/create@latest` 创建 Modern.js Module
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写项目名称：custom-commit
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
-```
-#### 实现自定义内容
-```ts title="src/index.ts"
-export async function getAddMessage() {}
-export async function getVersionMessage() {}
-```
-#### 将模块发布到 NPM
-#### 在目标仓库根目录安装对应模块，例如 `custom-commit`
-#### 配置 changeset 的 commit 配置为包名称
-```json title="package.json"
-{
-  "commit": "custom-commit",
-   ...
-}
-```
-### 使用 Monorepo 工程方案
-如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
-#### 执行 `pnpm run new` 创建模块子项目
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写子项目名称：custom-commit
-? 请填写子项目目录名称：custom-commit
-? 请选择开发语言：TS
-```
-#### 实现自定义内容
-```ts title="src/index.ts"
-export async function getAddMessage() {}
-export async function getVersionMessage() {}
-```
-#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-commit`
-```json title="package.json"
-{
-  "devDependencies": {
-    "custom-commit": "workspace:*",
-    ...
-  }
-}
-```
-#### 配置 changeset 的 commit 配置为包名称
-```json title=".changesets/config.json"
-{
-  "commit": "custom-commit",
-   ...
-}
-```
-该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

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 信息。
-具体命令支持的参数可以查看后续对应章节介绍。