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

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

@@ -0,0 +1,239 @@
+---
+sidebar_position: 6
+---
+
+# 自定义 Changelog 生成
+
+Changesets 默认会使用 `@changesets/cli/changelog` 生成 Changelog 信息，如果默认的 Changelog 信息不能满足需求，可以自定义 Changelog 的生成。
+
+## 自定义 Changlog 内容
+
+Changelog 信息主要包含以下两种信息：
+
+- changeset 中写入的 Changelog 信息。
+
+- 本次版本升级关联包的版本变更信息。
+
+自定义逻辑主要实现两个函数，`getReleaseLine` 和 `getDependencyReleaseLine`，分别用来定义上述这两种信息。
+
+### getReleaseLine
+
+#### Params
+
+- changeset
+
+```typescript
+export type VersionType = "major" | "minor" | "patch" | "none";
+
+export type Release = { name: string; type: VersionType };
+
+export type Changeset = {
+  id: string; // changeset 的文件名称
+  commit?: string; // changeset 提交时的 commit id 信息
+  summary: string; // changeset 内容信息
+  releases: Array<Release>; // 当前计算出的 changeset 升级包名称及类型信息
+};
+```
+
+- type
+
+当前包对应的升级版本类型，类型为上述 `VersionType`。
+
+#### 返回值
+
+Changelog 内容。
+
+#### 默认实现
+
+`@changesets/cli/changelog` 默认处理逻辑为将 `summary` 信息按照换行符 `\n` 分割，第一样前面增加 `-` 作为列表开头，其他内容作为第一行内容的补充整理在列表下方。
+
+```typescript
+async function getReleaseLine(changeset, type) {
+  const [firstLine, ...futureLines] = changeset.summary
+    .split('\n')
+    .map(l => l.trimRight());
+
+  let returnVal = `- ${
+    changeset.commit ? `${changeset.commit}: ` : ''
+  }${firstLine}`;
+
+  if (futureLines.length > 0) {
+    returnVal += `\n${futureLines.map(l => `  ${l}`).join('\n')}`;
+  }
+
+  return returnVal;
+}
+```
+
+### getDependencyReleaseLine
+
+#### Params
+
+- changesets
+
+当前关联的所有 changeset 信息，类型为 `getReleaseLine` changeset 类型数组。
+
+- dependenciesUpdated
+
+```typescript
+type ModCompWithPackage = {
+    name: string; // 依赖模块名称
+    type: VersionType; // 依赖模块的升级类型
+    oldVersion: string; // 依赖模块当前版本号
+    newVersion: string; // 依赖模块新版本号
+    changesets: string[]; // 关联的 changeset id 列表
+    packageJson: PackageJSON; // 依赖模块完整的 package.json 内容
+    dir: string; // 依赖模块的路径(绝对路径)
+};
+
+type DependenciesUpdated = ModCompWithPackage[]
+```
+
+#### 返回值
+
+Changelog 内容。
+
+#### 默认实现
+
+`@changesets/cli/changelog` 默认会使用 changesets 信息展示对应的 `Updated dependencies + commit id`，以列表形式展示。然后根据 `dependenciesUpdated` 信息展示对应的依赖包包名和新版本号，作为列表的子列表项。
+
+```typescript
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
+    console.log("getDependencyReleaseLine", changesets, dependenciesUpdated)
+    if (dependenciesUpdated.length === 0) return "";
+
+    const changesetLinks = changesets.map(
+      changeset =>
+        `- Updated dependencies${
+          changeset.commit ? ` [${changeset.commit}]` : ""
+        }`
+    );
+
+    const updatedDepenenciesList = dependenciesUpdated.map(
+      dependency => `  - ${dependency.name}@${dependency.newVersion}`
+    );
+
+    return [...changesetLinks, ...updatedDepenenciesList].join("\n");
+}
+```
+
+展示效果为：
+
+```markdown
+- Updated dependencies [f0438ab]
+- Updated dependencies [f0438ab]
+  - module-3@2.0.0
+  - module-1@0.2.0
+```
+
+## 配置
+
+Changesets 配置文件中 `changelog` 字段，该字段用于标记 Changelog 信息的获取途径。
+
+该配置可以为字符串，直接声明获取 Changelog 信息模块的模块名称或者路径。
+
+该配置还支持配置数组，数组中第一个元素为获取 Changelog 信息模块的模块名称或者路径，第二个元素为传入对应函数的参数值，会作为 `getReleaseLine` 和 `getDependencyReleaseLine` 函数的第三个参数传入。
+
+### 配置相对路径
+
+changelog 配置如果为相对路径为 `.changesets` 目录下的相对路径。
+
+例如创建 `.changeset/my-changelog-config.js` 文件，定义如下内容：
+
+```typescript title=".changeset/my-changelog-config.js"
+async function getReleaseLine(changeset, type) {}
+
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {}
+
+module.exports = {
+  getReleaseLine,
+  getDependencyReleaseLine,
+};
+
+```
+
+`changlog` 配置为 `./my-changelog-config.js` 即可:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-changelog-config.js",
+   ...
+}
+```
+
+### 使用模块工程方案
+
+自定义 Changelog 还可以使用模块工程方案进行管理，提供通用方案。
+
+#### 使用 `npx @modern-js/create` 创建模块工程方案。
+
+``` md
+? 请选择你想创建的工程类型 模块
+? 请填写项目名称 custom-changelog
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+#### 实现自定义内容。
+
+```typescript title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### 将模块发布到 NPM。
+
+#### 在目标仓库根目录安装对应模块，例如 `custom-changelog`。
+
+#### 配置 changeset 的 changelog 配置为包名称。
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+#### 执行 `pnpm run new` 创建模块子项目。
+
+``` md
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 custom-changelog
+? 请填写子项目目录名称 custom-changelog
+? 请选择开发语言 TS
+```
+
+#### 实现自定义内容。
+
+```typescript title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-changelog`。
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-changelog": "workspace: *",
+    ...
+  }
+}
+```
+
+#### 配置 changeset 的 changelog 配置为包名称。
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

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

@@ -0,0 +1,272 @@
+---
+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 信息
+
+```typescript
+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] 信息。
+
+```typescript
+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
+
+```typescript
+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] 信息。
+
+```typescript
+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 文件，定义如下内容：
+
+```javascript 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",
+   ...
+}
+```
+
+### 使用模块工程方案
+
+自定义 commit 还可以使用模块工程方案进行管理，提供通用方案。
+
+自定义 Changelog 还可以使用模块工程方案进行管理，提供通用方案。
+
+#### 使用 `npx @modern-js/create` 创建模块工程方案。
+
+``` md
+? 请选择你想创建的工程类型 模块
+? 请填写项目名称 custom-commit
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+#### 实现自定义内容。
+
+```typescript title="src/index.ts"
+export async function getAddMessage() {}
+
+export async function getVersionMessage() {}
+
+```
+
+#### 将模块发布到 NPM。
+
+#### 在目标仓库根目录安装对应模块，例如 custom-commit。
+#### 配置 changeset 的 commit 配置为包名称。
+
+```json title="package.json"
+{
+  "changelog": "custom-commit",
+   ...
+}
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+#### 执行 `pnpm run new` 创建模块子项目。
+
+``` md
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 custom-commit
+? 请填写子项目目录名称 custom-commit
+? 请选择开发语言 TS
+```
+
+#### 实现自定义内容。
+
+```typescript 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/zh/guides/topic-detail/changesets/config.md

@@ -0,0 +1,146 @@
+---
+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 信息](/docs/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](/docs/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`。