npm - @modern-js/main-doc - Versions diffs - 0.0.0-nightly-20240605170621 → 0.0.0-nightly-20240606170638 - Mend

@modern-js/main-doc 0.0.0-nightly-20240605170621 → 0.0.0-nightly-20240606170638

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