@modern-js/main-doc 2.52.0 → 2.54.0

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.

package/docs/en/guides/topic-detail/changesets/release-note.mdx

@@ -1,274 +0,0 @@
----
-sidebar_position: 8
----
-
-# Customizing Release Note Format
-
-Modern.js provides the `modern gen-release-note` command, which supports automatically generating Release Note through the current existing changeset and git commit information. Before running the release command, you can run this command to generate the Release Note for this release.
-
-The default generated Release Note format is:
-
-```markdown
-- fix: add missing type definitions by @zllkjc in https://github.com/web-infra-dev/modern.js/pull/3835
-```
-
-Get the Pull Request ID of the changeset through the commit information, and generate a Github link, which includes the changeset's changelog information and author information.
-
-:::info
-To get author information, you need to provide the Github Token environment variable, which is passed in through GITHUB_AUTH_TOKEN.
-:::
-
-When the default generated Release Note logic cannot meet the requirements, custom Release Note format is supported.
-
-## Information
-
-### getReleaseInfo
-
-To generate Release Note information, some information needs to be collected, such as commit ID, Pull Request ID, commit message, etc.
-
-This logic can be implemented through the `getReleaseInfo` function.
-
-#### Params
-
-- commit
-
-Type: string;
-
-The commit message information corresponding to the current changeset.
-
-The result of executing `git log --pretty=format:%h--%s--%ae .changeset/${changeset.id}.md`.
-
-- commitObj
-
-Basic information about 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 information passed in as a parameter or defined in package.json
-  pullRequestId?: string;
-  author?: string;
-  message: string; // Commit message
-  summary: string; // Changeset summary
-  summary_zh: string; // Changeset summary in Chinese
-  [key: string]: string | undefined;
-}
-```
-
-#### Returns
-
-commitObj, the complete commit object after supplementation.
-
-#### Default Implementation
-
-The default implementation of Modern.js is to split out the Pull Request ID based on the commit information, and get the user information based on the commit ID and add it to the 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
-
-Generate the corresponding Release Note based on the commit object information getted in `getReleaseInfo`.
-
-This logic can be implemented through the `getReleaseNoteLine` function.
-
-#### Params
-
-- commit
-
-The type is the same as the above `commitObj` type.
-
-- lang
-
-Type: string;
-
-Get the Release Note information of the corresponding language, supporting `en` and `zh`, the default is `en`.
-
-#### Returns
-
-The generated Release Note.
-
-#### Default Implementation
-
-The default implementation of Modern.js is:
-
-```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`;
-}
-```
-
-## Using Custom Modules
-
-The `gen-release-note` command supports the `--custom` parameter, which can pass in the module name or path of the custom Release Note module.
-
-### Configuring Relative Paths
-
-If the custom parameter value is a relative path, it is the **project root directory**.
-
-For example, create the `scripts/my-release-note-config.js` file and define the following content:
-
-```ts title="scripts/my-release-note-config.js"
-function getReleaseInfo(commit, commitObj) {
-  return commitObj;
-}
-
-function getReleaseNoteLine(commit) {}
-
-module.exports = {
-  getReleaseInfo,
-  getReleaseNoteLine,
-};
-```
-
-Run the following command:
-
-```bash
-pnpm run gen-release-note --custom ./scripts/my-release-note-config.js
-```
-
-You can also define the command parameters directly in `package.json`:
-
-```json title="package.json"
-{
-    "scripts": {
-        ...
-        "gen-release-note": "modern gen-release-note --custom ./scripts/my-release-note-config.js"
-    },
-    ...
-}
-```
-
-Run the command `pnpm run gen-release-note` directly.
-
-### Using Modern.js Module
-
-Customizing release note can also be managed using the Modern.js Module to provide a common solution.
-
-#### Use `npx @modern-js/create@latest` to create a Modern.js Module
-
-```md
-? Please select the type of project you want to create: Npm Module
-? Please fill in the project name: custom-release-note
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-```
-
-#### Implement Custom Content
-
-```ts title="src/index.ts"
-export function getReleaseInfo() {}
-
-export function getReleaseNoteLine() {}
-```
-
-#### Publish the module to NPM
-#### Install the corresponding module in the root directory of the target repository, such as `custom-release-note`
-#### Run the `gen-release-note` command with the `custom` parameter added
-
-```bash
-pnpm run gen-release-note --custom custom-release-note
-```
-
-### 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
-
-```md
-? Please select the type of project you want to create: Npm Module
-? Please fill in the sub-project name: custom-release-note
-? Please fill in the sub-project directory name: custom-release-note
-? Please select the programming language: TS
-```
-
-#### Implement Custom Content
-
-```ts title="src/index.ts"
-export function getReleaseInfo() {}
-
-export function getReleaseNoteLine() {}
-```
-
-#### Add the sub-project module dependency, such as `custom-release-note`, to the Monorepo root directory
-
-```json title="package.json"
-{
-  "devDependencies": {
-    "custom-release-note": "workspace:*",
-    ...
-  }
-}
-```
-
-#### Run the `gen-release-note` command with the `custom` parameter added
-
-```bash
-pnpm run gen-release-note --custom custom-release-note
-```
-
-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/release-pre.mdx

@@ -1,49 +0,0 @@
----
-sidebar_position: 4
----
-
-# Publishing Pre-Release Version
-
-Before doing an actual release, we also need to publish a pre-release version for internal testing and user use. Changesets also support publishing pre-release versions.
-
-## Steps
-
-:::info
-The following example commands are all using pnpm. If you need to use other package managers, please replace them as needed.
-:::
-
-#### Run the bump command to upgrade the version of the pre-release
-
-```bash
-pnpm run bump --canary --preid <preid>
-```
-
-`preid` is the tag for the pre-release version, such as `alpha`, `beta`, etc., and the default value is `next`.
-
-After using the `--canary` parameter, the `bump` command completes the following three steps:
-
-- `changeset pre enter <preid>`: Enters pre-release mode.
-
-- `changeset version`: Upgrades the version.
-
-- `changeset pre exit`: Exits pre-release mode.
-
-#### Check the changes and submit
-
-Check whether the version changes are correct and submit the changes.
-
-It is recommended to perform pre-release operations not on the main branch and not merge them into the main branch. After the pre-release verification is completed, an actual version can be directly released based on the main branch.
-
-#### Run the release command to publish the pre-release version:
-
-```bash
-pnpm run release --tag <tag>
-```
-
-When publishing a pre-release version, you must use the `--tag` parameter. The parameter value is best the same as the `preid` value to facilitate user use.
-
-## Notes
-
-### Exiting pre-release mode
-
-After entering pre-release mode, changesets will automatically create a `pre.json` file in the `.changeset` directory to record some status information when entering pre-release mode. When the status information is inconsistent with the current repository status, you can directly delete this file to exit pre-release mode.