@modern-js/main-doc 0.0.0-next-1686023023547 → 0.0.0-next-1686037191101

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-1686023023547
+## 0.0.0-next-1686037191101
 
 ### Patch Changes
 
@@ -8,7 +8,11 @@
 
   docs: 修复 reset command 翻译问题
 
-  - @modern-js/builder-doc@0.0.0-next-1686023023547
+- 7267a1ae6c: docs(main): update changeset doc
+
+  docs(main): 更新包版本管理文档
+
+  - @modern-js/builder-doc@0.0.0-next-1686037191101
 
 ## 2.22.0
 

package/docs/en/configure/app/tools/swc.mdx

@@ -19,23 +19,9 @@ When using Rspack as the bundler, SWC will be used for transpiling and compressi
 
 ## Install
 
-First, you need to execute `pnpm run new` to enable the SWC compile:
+import EnableSWC from '@modern-js/builder-doc/docs/en/shared/enable-swc.md';
 
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable SWC Compile
-```
-
-After the installation, please register the SWC plugin in the `modern.config.ts` file, then the SWC compilation and compression will be enabled.
-
-```ts title="modern.config.ts"
-import appTools, { defineConfig } from '@modern-js/app-tools';
-import swcPlugin from '@modern-js/plugin-swc';
-
-export default defineConfig({
-  plugins: [appTools(), swcPlugin()],
-});
-```
+<EnableSWC />
 
 ## Config
 

package/docs/en/guides/topic-detail/changesets/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Package Version Management",
+  "position": 5
+}

package/docs/en/guides/topic-detail/changesets/add.mdx

@@ -0,0 +1,123 @@
+---
+sidebar_position: 2
+---
+
+# Add Changesets
+
+When we finish development, we need to add a changeset to declare the current changes for future version releases.
+
+## Information
+
+A changeset includes:
+
+- Which packages are affected by this change.
+
+- The type of version number upgrade needed for this change, which complies with the [semver](https://semver.org/) specification.
+
+- Changelog information for this change.
+
+## Steps
+
+:::info
+The following example commands are all using pnpm as the package management tool. If you need to use other package management tools, please replace them as needed.
+:::
+
+### Module project scheme
+
+#### Run the following command in the root directory:
+
+```bash
+pnpm run change
+```
+
+#### Select the type of version number upgrade needed for this change and press Enter:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-version.png)
+
+#### Fill in the changelog information and press Enter twice:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog.png)
+
+After running, a corresponding changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+'module-changeset': patch
+---
+
+feat: test module solution changeset
+```
+
+This file contains all the information of the changeset.
+
+### Monorepo
+
+Assuming there are three module packages in the monorepo, `module-1`, `module-2`, and `module-3`.
+
+#### Run the following command in the root directory:
+
+```bash
+pnpm run change
+```
+
+#### Select the list of packages to upgrade for this change:
+
+Changesets will categorize the packages in the Monorepo into two categories, `changed packages` and `unchanged packages`, based on the current code changes (`git diff Head...baseBranch`), making it easy for users to choose.
+
+Use the space key to select the corresponding package or category, and then press Enter after the selection is completed:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-packages.png)
+
+#### Select the packages corresponding to different version types. Changesets will ask about the `major` and `minor` types. If there are packages that have not selected these two types, the `patch` type will be used by default:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-auto-select-patch.png)
+
+#### Fill in the changelog information and press Enter twice:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog-monorepo.png)
+
+After running, a corresponding changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+'module-2': minor
+'module-3': patch
+---
+
+feat: test-changeset
+```
+
+This file contains all the information of the changeset, and different packages will be marked according to the selected version type.
+
+## Parameters
+
+The `change` command supports the following parameters:
+
+- `--empty` Adds an empty changeset.
+
+```bash
+pnpm run change --empty
+```
+
+After running, an empty changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+---
+```
+
+- `--open` When using this parameter, the system default editor will be opened for filling in the changelog.
+
+## Notes
+
+- Not all changes require changesets
+
+If the current change is to modify some infrastructure of the repository, such as CI, testing, etc., there is no need to add changesets, or an empty changeset can be added.
+
+- Multiple changesets can be submitted in one pull request
+
+When a pull request has multiple feature developments or bug fixes, multiple `pnpm run change` commands can be executed to add multiple changeset files. Each file selects the corresponding packages for the feature and adds change information.
+
+- When creating a changeset, all packages related to the feature need to be selected
+
+When creating a changeset in a Monorepo, all related packages to the feature need to be selected to avoid some packages not being published when releasing.

package/docs/en/guides/topic-detail/changesets/changelog.mdx

@@ -0,0 +1,238 @@
+---
+sidebar_position: 6
+---
+
+# Customizing Changelog Generation
+
+By default, Changesets will use `@changesets/cli/changelog` to generate changelog information. If the default changelog information cannot meet the requirements, you can customize the generation of changelog.
+
+## Customizing Changelog Content
+
+Changelog information mainly includes the following two types of information:
+
+- Changelog information written in the changeset.
+
+- Version change information of related packages in this version upgrade.
+
+The custom logic mainly implements two functions, `getReleaseLine` and `getDependencyReleaseLine`, which are used to define the above two types of information, respectively.
+
+### getReleaseLine
+
+#### Params
+
+- changeset
+
+```ts
+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
+
+The upgraded version type corresponding to the current package, which is of type `VersionType` mentioned above.
+
+#### Returns
+
+Changelog content.
+
+#### Default Implementation
+
+The default processing logic of `@changesets/cli/changelog` is to split the `summary` information according to the newline `\n`, add `-` as the list header before the first line, and organize other content as the supplement of the first line below the list.
+
+```ts
+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
+
+All associated changeset information, which is an array of `getReleaseLine` changeset types.
+
+- dependenciesUpdated
+
+```ts
+type ModCompWithPackage = {
+  name: string; // 依赖模块名称
+  type: VersionType; // 依赖模块的升级类型
+  oldVersion: string; // 依赖模块当前版本号
+  newVersion: string; // 依赖模块新版本号
+  changesets: string[]; // 关联的 changeset id 列表
+  packageJson: PackageJSON; // 依赖模块完整的 package.json 内容
+  dir: string; // 依赖模块的路径(绝对路径)
+};
+
+type DependenciesUpdated = ModCompWithPackage[];
+```
+
+#### Returns
+
+Changelog content.
+
+#### Default Implementation
+
+By default, `@changesets/cli/changelog` will display the corresponding `Updated dependencies + commit id` information of the changesets as a list. Then, based on the `dependenciesUpdated` information, it will display the package name and new version number of the corresponding dependency package as a child list item of the list.
+
+```ts
+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');
+}
+```
+
+It is displayed as follows:
+
+```markdown
+- Updated dependencies [f0438ab]
+- Updated dependencies [f0438ab]
+  - module-3@2.0.0
+  - module-1@0.2.0
+```
+
+## Configuration
+
+The `changelog` field in the changesets configuration file is used to mark the way to obtain changelog information.
+
+This configuration can be a string, directly declaring the module name or path of the changelog information acquisition module.
+
+This configuration also supports configuring arrays. The first element in the array is the module name or path of the changelog information acquisition module, and the second element is the parameter value passed to the corresponding function, which will be passed as the third parameter of the `getReleaseLine` and `getDependencyReleaseLine` functions.
+
+### Configuring Relative Paths
+
+If the changelog configuration is a relative path, it is a relative path under the `.changesets` directory.
+
+For example, create the `.changeset/my-changelog-config.js` file and define the following content:
+
+```ts title=".changeset/my-changelog-config.js"
+async function getReleaseLine(changeset, type) {}
+
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {}
+
+module.exports = {
+  getReleaseLine,
+  getDependencyReleaseLine,
+};
+```
+
+Configure `changlog` as `./my-changelog-config.js`:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-changelog-config.js",
+   ...
+}
+```
+
+### Using Module Project
+
+Customizing changelog can also be managed using the module project to provide a common solution.
+
+#### Use `npx @modern-js/create@latest` to create a module project.
+
+```md
+? Please select the type of project you want to create: Npm Module
+? Please fill in the project name: custom-changelog
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### Publish the module to NPM.
+
+#### Install the corresponding module in the root directory of the target repository, such as `custom-changelog`.
+
+#### Configure the changelog configuration of Changesets as the package name.
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+### Using Monorepo Sub-Project
+
+If your current repository is Monorepo, you can directly manage it using module sub-projects.
+
+#### Run `pnpm run new` to create a module sub-project.
+
+```bash
+? Please select the type of project you want to create: Npm Module
+? Please fill in the sub-project name: custom-changelog
+? Please fill in the sub-project directory name: custom-changelog
+? Please select the programming language: TS
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### Add the sub-project module dependency, such as `custom-changelog`, to the Monorepo root directory.
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-changelog": "workspace: *",
+    ...
+  }
+}
+```
+
+#### Configure the changelog configuration of Changesets as the package name.
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+After the module is published to NPM, it can still be used like a module type for other repositories.

package/docs/en/guides/topic-detail/changesets/commit.mdx

@@ -0,0 +1,269 @@
+---
+sidebar_position: 7
+---
+
+# Customizing Commit Messages
+
+Changesets supports configuring `commit` to automatically submit the current changes when executing the `change` and `bump` commands.
+
+The default `commit` information is provided by `@changesets/cli/commit`, and the default information format is:
+
+![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)
+
+When the default commit information cannot meet the requirements, custom commit information is supported.
+
+## Customizing Commit Message Content
+
+Commit information is divided into two types:
+
+- Commit information automatically generated when executing the `change` command.
+- Commit information automatically generated when executing the `bump` command.
+
+The custom logic mainly implements two functions, `getAddMessage` and `getVersionMessage`, which are used to define the above two types of information, respectively.
+
+### getAddMessage
+
+#### Params
+
+- changeset
+
+The current changeset information created.
+
+```ts
+type Release = {
+  name: string;
+  type: VersionType;
+};
+
+type Changeset = {
+  summary: string;
+  releases: Array<Release>;
+};
+```
+
+- options
+
+Configuration information when committing.
+
+> When the commit configuration is an array, the second parameter supports passing in default configuration information, which will be used to pass this parameter.
+
+#### Returns
+
+Commit message content.
+
+#### Default Implementation
+
+The default processing logic of `@changesets/cli/commit` is to start with `docs(changeset):`, and the commit information is the `summary` of the changeset, and [skip ci] information is added according to the `skipCI` parameter configuration passed in.
+
+```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) is used to remove the leading whitespace content of the template string to make the commit information more compliant with the specification.
+
+### 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
+
+Configuration information when committing.
+
+> When the commit configuration is an array, the second parameter supports passing in default configuration information, which will be used to pass this parameter.
+
+#### Returns
+
+Commit message content.
+
+#### Default Implementation
+
+The default processing logic of `@changesets/cli/commit` is to first display the number of packages that need to be released, then display the names and new version numbers of the released packages, and [skip ci] information is added according to the `skipCI` parameter configuration passed in.
+
+```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` : ''}
+`;
+};
+```
+
+## Configuration
+
+The `commit` field in the changesets configuration file is used to mark whether to submit commit information when executing the `change` and `bump` commands, and the way to obtain commit information.
+
+This configuration can be a `boolean`. When it is `true`, the default `@changesets/cli/commit` formatting commit information will be used.
+
+This configuration can be a string, directly declaring the module name or path of the commit information acquisition module.
+
+This configuration also supports configuring arrays. The first element in the array is the module name or path of the commit information acquisition module, and the second element is the parameter value passed to the corresponding function, which will be passed as the second parameter of the `getAddMessage` and `getVersionMessage` functions.
+
+### Configuring Relative Paths
+
+If the commit configuration is a relative path, it is a relative path under the `.changesets` directory.
+
+For example, create the `.changeset/my-commit-config.js` file and define the following content:
+
+```js title=".changeset/my-commit-config.js"
+async function getAddMessage(changeset, options) {}
+
+async function getVersionMessage(releasePlan, options) {}
+
+module.exports = {
+  getAddMessage,
+  getVersionMessage,
+};
+```
+
+Configure `commit` as `./my-commit-config.js`:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-commit-config.js",
+   ...
+}
+```
+
+### Using Module Project
+
+Customizing commit can also be managed using the module project to provide a common solution.
+
+#### Use `npx @modern-js/create@latest` to create a module project.
+
+```md
+? Please select the type of project you want to create: Npm Module
+? Please fill in the project name: custom-changelog
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getAddMessage() {}
+
+export async function getVersionMessage() {}
+```
+
+#### Publish the module to NPM.
+
+#### Install the corresponding module in the root directory of the target repository, such as `custom-commit`.
+
+#### Configure the commit configuration of changesets as the package name.
+
+```json title="package.json"
+{
+  "commit": "custom-commit",
+   ...
+}
+```
+
+### Using Monorepo Sub-Project
+
+If your current repository is Monorepo, you can directly manage it using module sub-projects.
+
+#### Run `pnpm run new` to create a module sub-project.
+
+```bash
+? Please select the type of project you want to create: Npm Module
+? Please fill in the sub-project name: custom-commit
+? Please fill in the sub-project directory name: custom-commit
+? Please select the programming language: TS
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getAddMessage() {}
+
+export async function getVersionMessage() {}
+```
+
+Add the sub-project module dependency, such as `custom-commit`, to the Monorepo root directory.
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-commit": "workspace: *",
+    ...
+  }
+}
+```
+
+Configure the commit configuration of Changesets as the package name.
+
+```json title=".changesets/config.json"
+{
+  "commit": "custom-commit",
+   ...
+}
+```
+
+After the module is published to NPM, it can still be used like a module type for other repositories.