@modern-js/main-doc 2.51.0 → 2.53.0

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

@@ -1,269 +0,0 @@
----
-sidebar_position: 7
----
-
-# Customizing Commit Messages
-
-Changesets supports configuring `commit` to automatically submit the current changes when running 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 running the `change` command.
-- Commit information automatically generated when running 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'; // Current state of pre mode
-  tag: string; // Type of pre
-  initialVersions: {
-    [pkgName: string]: string; // Package name and version information before version upgrade
-  };
-  changesets: string[]; // List of changeset ids for this upgrade
-};
-
-type ReleasePlan = {
-  changesets: Changeset[]; // List of changesets for this upgrade
-  releases: ComprehensiveRelease[]; // Information of the current upgrade, including package name, current version, upgraded version, and upgrade type
-  preState: PreState | undefined; // If it is a pre-release, provide relevant state information
-};
-```
-
-- 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 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 running 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 Modern.js Module
-
-Customizing commit can also be managed using the Modern.js Module to provide a common solution.
-
-#### Use `npx @modern-js/create@latest` to create a mModern.js Module
-
-```md
-? Please select the type of project you want to create: Npm Module
-? Please fill in the project name: custom-commit
-? 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 NPM 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.

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

@@ -1,147 +0,0 @@
----
-sidebar_position: 5
----
-
-# Changesets Configuration
-
-When initializing a Modern.js repository, the configuration file for changesets will be initialized by default, that is, the `.changeset/config.json` file. Below, we will learn in detail what configurations are supported in this file.
-
-## Introduction
-
-### commit
-
-Type: `boolean`
-
-Default: `false`
-
-When this field is configured as `true`, the code submission operation will be automatically executed when running the `change` and `bump` commands.
-
-The default commit information format is as follows:
-
-![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)
-
-This commit information supports customization, which we will discuss in detail in the [Customizing Commit Messages](/guides/topic-detail/changesets/commit) chapter.
-
-### access
-
-Type: `restricted` | `public`
-
-Default: `restricted`
-
-Used to configure the publishing form of the current package. If configured as `restricted`, it will be published as a private package. If it is `public`, it will be published as a public scope package.
-
-For packages that need to configure access in the repository, `publishConfig` can be configured in `package.json`, for example:
-
-```json title=package.json
-{
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  }
-}
-```
-
-For packages that don't need to be published, you can set `private` to `true` in `package.json` to prevent them from being published.
-
-### baseBranch
-
-Type: `string`
-
-Default: `main`
-
-Repository main branch. This configuration is used to calculate the changed packages of the current branch and classify them.
-
-### ignore
-
-Type: `string[]`
-
-Default: `[]`
-
-Used to declare packages to be ignored when running the `bump` command. The usage is consistent with the `--ignore` parameter of the `bump` command. Note that the two cannot be used at the same time.
-
-### fixed
-
-Type: `string[][]`
-
-Default: `[]`
-
-Used to group packages in monorepos. The version of packages in the same group will be bound, and each time the `bump` command is run, a package in the same group is upgraded, others will be upgraded together.
-Regular expressions can be used to match package names.
-
-### linked
-
-Type: `string[][]`
-
-Default: `[]`
-
-Similar to `fixed`, it also groups packages in monorepos, but only the packages related to the changeset declaration will be upgraded when the `bump` command is run, and the version of the changeset packages in the same group will remain consistent.
-Regular expressions can be used to match package names.
-
-### updateInternalDependencies
-
-Type: `patch` | `minor`
-
-Default: `patch`
-
-Used to declare the version number rule for updating internal dependencies.
-
-When upgrading the version number by running the `bump` command, the dependency declaration using the package in the repository will be automatically updated by default. After configuring this field as `minor`, if the version number is upgraded to `patch`, the reference dependency declaration will not be updated automatically.
-
-For example:
-
-```
-pkg-a @ version 1.0.0
-pkg-b @ version 1.0.0
-  depends on pkg-a at range `^1.0.0
-```
-
-By default, when upgrading `pkg-a` to `1.0.1`, the dependency version of `pkg-a` in `pkg-b` will be updated to `^1.0.1`.
-
-When configuring `updateInternalDependencies` as `minor`, when upgrading `pkg-a` to `1.0.1`, the dependency version of `pkg-a` in `pkg-b` will not be updated. Only when the version number of `pkg-a` is upgraded to `1.1.0` or `2.0.0`, the dependency of `pkg-a` in `pkg-b` will be updated.
-
-### changelog
-
-Type: `boolean` | `string` | `[string, unknow]`
-
-Default: `@changesets/cli/changelog`
-
-The rule for generating changelog.
-
-When configured as `false`, only the version number will be declared in the `CHANGELOG.md` file when running the `bump` command, and no other changelog information will be declared.
-
-![Close changelog configuration](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-empty-changelog.png)
-
-When configured as `@changesets/cli/changelog`, the official provided changelog generation rule will be used to convert the changeset information into changelog content.
-
-When configured as an array, the first parameter is a custom NPM package or path, and the second parameter is the default parameter configuration that needs to be passed in. We will explain the custom format in the subsequent [Custom Changelog](/guides/topic-detail/changesets/changelog) section.
-
-### \_\_\_experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH
-
-Some experimental configurations.
-
-#### onlyUpdatePeerDependentsWhenOutOfRange
-
-Type: `boolean`
-
-Default: `false`
-
-Configuration for the upgrade strategy of `peerDependence` dependencies. By default, when `peerDependence` is upgraded to a `minor` or `major` version, the current package will be upgraded to a major version.
-
-When this configuration is set to `true`, the version will only be updated when the declared dependencies of `peerDependence` are outside the declared range.
-
-#### updateInternalDependents
-
-Type: `always` | `out-of-range`
-
-Default: `always`
-
-When upgrading the version number by running the `bump` command, the dependency declaration using the package in the repository will be automatically updated by default. When this parameter is set to `out-of-range`, the dependency declaration using the package in the repository will be updated only when it is outside the declared range.
-
-#### useCalculatedVersionForSnapshots
-
-Type: `boolean`
-
-Default: `false`
-
-When publishing snapshots, the version format of `0.0.0-timestamp` will be used by default to ensure that users can use pre-release versions normally. When you need to ignore the above problem and use the normal version number format, that is, the current version is `1.0.1`, and the snapshot version is expected to use `1.0.1-timestamp`, you can configure this parameter as `true`.

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

@@ -1,175 +0,0 @@
----
-sidebar_position: 9
----
-
-# Using Github related tools
-
-## BOT
-
-On Github, changesets provide a robot to detect whether the current Pull Request has changeset, and provide a UI interface to add and modify changeset.
-
-### Installation
-
-Click [link](https://github.com/apps/changeset-bot), select Install in the upper right corner, and confirm to complete the installation.
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-install-bot.png)
-
-### Configuration
-
-After successful installation, you can enter the configuration page and select the application repository according to your needs.
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-config-bot.png)
-
-### Usage
-
-After the configuration is completed, the robot will automatically check whether each Pull Request has added changeset and provide prompt information through reply.
-
-#### No changeset added
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-no-changeset.png)
-
-You can run `pnpm run change` in the repository to add changeset, or click the second link below to fill in changeset directly.
-
-#### Changeset added
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-exist-changeset.png)
-
-You can click the link below to modify and add new changeset.
-
-#### No need for changeset
-
-You can directly ignore the prompt information when no changeset is added, which will not cause problems with the merging of Pull Requests.
-
-## Action
-
-### Automatically create Release Pull Request
-
-Modern.js provides a Github Action to automatically create release Pull Request, which can automatically run bump command, update lock file and create Pull Request operation based on the selected branch.
-
-#### Usage
-
-- Create a `.github/workflows/release-pull-request.yml` file in the repository and fill in the following content:
-
-```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 }}
-```
-
-- After merging Workflow into the main branch, go to the Action page corresponding to the Github repository and select Release Pull Request:
-
-![Release Pull Request Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/action-pull-request.png)
-
-- Select the release type of this release, and click the Run workflow button:
-
-![Run Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/action-pull-request.jpeg)
-
-- After the workflow is completed, a `Release-${version}` Pull Request will be automatically created, the related version number of `bump` changeset will be automatically updated, and the lock file will be updated. The content of Pull Request is the Release Note automatically generated by running the `gen-release-note` command.
-
-![Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-pull-request.jpeg)
-
-### Automatic Release
-
-Modern.js provides a Github Action to automatically release versions, which can automatically run release command based on the selected branch and publish the package to NPM.
-
-#### Usage
-
-- Create a `.github/workflows/release.yml` file in the repository and fill in the following content:
-
-```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 }}
-```
-
-- Configure the NPM_TOKEN of the repository:
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/github-set-npm-token.png)
-
-- After merging Workflow into the main branch, go to the Action page corresponding to the Github repository and select Release:
-
-![Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-action.png)
-
-- Select the branch name and release version type, and click the Run workflow button:
-
-![Run Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/run-release-workflow.png)
-
-- Workflow will automatically complete the build and release to NPM process of the repository.

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

@@ -1,56 +0,0 @@
----
-sidebar_position: 1
----
-
-# Introducing Changesets
-
-Modern.js integrates [changesets](https://github.com/changesets/changesets) for package version management in Npm Module and Monorepo project.
-
-## Features
-
-Changesets have the following features:
-
-- During development, developers need to provide the package names, the type of version upgrade (`pathch`, `minor`, `major`), and change information involved in this change.
-
-- When releasing a version, the version number of the corresponding package will be automatically upgraded based on the content of the changeset, and changelog information will be generated in the corresponding package.
-
-- In the Monorepo project, changesets will automatically generate a repository dependency graph, and only upgrade the version numbers of the changed packages and related dependent packages during upgrade.
-
-## Initialization
-
-The Npm Module and Monorepo project created by Modern.js have already initialized changesets. The `.changeset` directory and the configuration file `.changeset/config.json` will be automatically created in the project root directory.
-
-In addition, Modern.js provides corresponding commands for changesets in its corresponding project tools `@modern-js/module-tools` and `@modern-js/monorepo-tools`, and there is no need to manually install changeset-related dependencies.
-
-The default configuration for changesets is as follows:
-
-```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": []
-}
-```
-
-The configuration file provides some basic configurations for generating changesets. For detailed field descriptions, please refer to [Changesets configuration](/guides/topic-detail/changesets/config).
-
-## Commands
-
-- `change`: Creates a changeset. After running this command, a changeset file will be automatically generated in the `.changeset` directory.
-
-- `bump`: Upgrades the version of the corresponding package based on the current changeset.
-
-- `pre`: Marks entering and exiting `pre release` mode. When running the `bump` command in `pre release` mode, the version format will be `x.x.x-${pre-tag}.x`.
-
-- `release`: Publishes the package to NPM.
-
-- `status`: Views the current changeset status.
-
-- `gen-release-note`: Generates Release Note information based on the current chagneset status.
-
-For specific command-supported parameters, please refer to the corresponding chapter introduction.