npm - @modern-js/main-doc - Versions diffs - 2.51.0 → 2.53.0 - Mend

@modern-js/main-doc 2.51.0 → 2.53.0

Files changed (68) hide show

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

@@ -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 DELETED Viewed

@@ -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.

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

@@ -1,229 +0,0 @@
----
-sidebar_position: 3
----
-# Publishing Version
-When releasing a version, we need to upgrade the version of the corresponding packages based on the changeset generated during development, and run the publish command to publish them to NPM.
-## Steps
-:::info
-The following example commands are all using pnpm. If you need to use other package managers, please replace them as needed.
-:::
-### Modern.js Module
-#### Run the bump command in the root directory
-```bash
-pnpm run bump
-```
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-bump.png)
-When running this command, changesets will automatically perform the following operations:
-- Delete all changeset files under the `.changesets` directory.
-- Upgrade the package version based on the changeset information.
-- Write changelog information to the `CHANGELOG.md` file in the root directory. The file will be automatically created if it does not exist.
-#### Confirm and submit the current changes
-```bash
-git add .
-git commit -m "release: bump package"
-```
-#### Run the release command in the root directory to publish the package to NPM
-```bash
-pnpm run release
-```
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-release.png)
-#### Push the tag to the remote repository
-```bash
-git push --follow-tags
-```
-### Monorepo
-#### Run the bmp command in the root directory
-```bash
-pnpm run bump
-```
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
-When running this command, changesets will automatically perform the following operations:
-- Delete all changeset files under the `.changesets` directory.
-- Upgrade the version of the relevant packages based on the changeset information. In addition to the packages written in the changeset, changesets will also analyze the dependency graph of all packages in the Monorepo during running. If is required, the version will be automatically upgraded accordingly.
-- Write changelog to the `CHANGELOG.md` file in the directory of the package that needs to be upgraded. The file will be automatically created if it does not exist.
-#### Confirm and submit the current changes
-:::info
-Make sure that the automatically upgraded version meet the expected requirements. If you need to understand the version upgrade strategy, please refer to [Version Upgrade Strategy](/guides/topic-detail/changesets/release#version-upgrade-strategy).
-:::
-```bash
-git add .
-git commit -m "release: bump package"
-```
-#### Run the release command in the root directory to publish the package to NPM
-```bash
-pnpm run release
-```
-When running this command, it will sequentially determine whether the versions of all packages in the Monorepo exist on NPM. If they do not exist, the `publish` command will be run to publish them.
-:::warning
-When the dependencies between packages in the Monorepo are declared using workspace, do not directly run `npm publish` to publish the package in the corresponding subdirectory of the package. Use the `release` command instead. When publishing, the workspace declaration will be automatically removed to ensure that the NPM package is available after publishing.
-:::
-#### Push the tag to the remote repository
-```bash
-git push --follow-tags
-```
-## Parameters
-### Parameters for the `bump` command
-- `--snapshot`: Generates a timestamp-based version.
-```bash
-pnpm run bump --snapshot canary
-```
-After running, the corresponding upgraded version will become `0.0.0-canary-20220622092823`, and `canary` is the tag configured for snapshot. If not configured, it will directly generate the form of `0.0.0-20220622092823`.
-This parameter is mainly used to publish temporary test versions for testing and does not require code submission.
-- `--ignore`: Manually ignore some packages during publishing.
-For example, if you need to ignore the `module-2` package for this release:
-```bash
-pnpm run bump --ignore module-2
-```
-After running the command, the update of the `module-2` package will be ignored. Note that if there are packages that depend on `module-2`, the corresponding packages also need to be added to the `ignore` parameter, otherwise the `bump` command will fail.
-The usage for adding multiple packages is as follows:
-```bash
-pnpm run bump --ignore module-2 --ignore module-3
-```
-### Parameters for the `release` command
-- `--otp`: Uses `npm token` to publish the package.
-```bash
-pnpm run relese --otp <token>
-```
-- `--tag`: Uses a specific tag for publishing, and `latest` is used by default.
-```bash
-pnpm run release --tag <tag>
-```
-- `--ignore-scripts`: Ignores npm scripts during publishing.
-When running the `publish` command, npm will automatically trigger many commands, such as `prepare` and `prepublish`. Using this parameter can ignore the running of these commands. This parameter is only supported in Monorepo using pnpm.
-```bash
-pnpm run release --ignore-scripts
-```
-- `--no-git-checks`: Ignores checking the current branch during publishing.
-By default, when running the `release` command, it will automatically check whether the current branch is a release branch, whether there are uncommitted changes, etc. Using this parameter can ignore git-related checks.
-```bash
-pnpm run release --no-git-checks
-```
-## Version Upgrade Strategy
-### dependencies or devDependencies
-- Only upgrade the patch version of the package itself for patch version
-For example, the following scenario exists:
-There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `dependencies` of `module-2`.
-The current changeset is the patch version upgrade of `module-1`.
-After running the `bump` command, only the patch version of `module-1` will be upgraded.
-- Upgrade the major or minor version of the package itself for major/minor version upgrades, and upgrade the patch version of the dependent packages
-For example, the following scenario exists:
-There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `dependencies` of `module-2`.
-The current changeset is the minor version upgrade of `module-1`.
-After running the `bump` command, `module-1` will upgrade the `minor` version, and `module-2` will upgrade the `patch` version number.
-### peerDependencies
-- Upgrade the patch version of the package itself and the dependent package for patch version dependencies
-For example, the following scenario exists:
-There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`.
-The current changeset is the patch version upgrade of `module-1`.
-After running the `bump` command, both `module-1` and `module-2` will upgrade the patch version.
-- Upgrade the major version of the dependent package for major/minor version upgrades of the package itself
-For example, the following scenario exists:
-There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`.
-The current changeset is the minor version upgrade of `module-1`.
-After running the bump command, `module-1` will upgrade the `minor` version, and `module-2` will upgrade the `major` version number.
-- Modify the upgrade strategy for peerDependencies
-The upgrade strategy of `peerDependencies` can be modified by configuring `onlyUpdatePeerDependentsWhenOutOfRange`. When only the declared version type range is exceeded, the corresponding `peerDependencies` will be upgraded.
-```json
-{
-  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
-    "onlyUpdatePeerDependentsWhenOutOfRange": true
-  },
-  ...
-}
-```
-For example, the following scenario exists:
-There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`, and the version of `module-1` is declared using `^`.
-The current changeset is the patch or minor version upgrade of `module-1`.
-After running the `bump` command, only the version of `module-1` will be upgraded.
-Note that if the package version is in the `0.x.x` range, upgrading the `minor` version is also beyond the declared version type range.

package/docs/en/guides/topic-detail/model/test-model.mdx DELETED Viewed

@@ -1,45 +0,0 @@
----
-sidebar_position: 9
-title: Test Model
----
-# Test Model
-Testing is crucial for the stability of code. Here's an example using the `countModel` from [Quick Start](/guides/topic-detail/model/quick-start) to demonstrate how to perform unit testing on a Model in Modern.js.
-To use the testing feature, you need to first enable it. In the project root directory, execute `pnpm run new` and make the following selection:
-```bash
-? Please select the operation you want to perform: Enable optional features
-? Enable optional features Enable "Unit Testing / Integration Testing" feature
-```
-This will enable testing feature support.
-Create a new file called `count.test.ts` with the following code:
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import countModel from './count';
-describe('test model', () => {
-  it('count value should plus one after add', () => {
-    const store = createStore();
-    const [state, { add }] = store.use(countModel);
-    expect(state).toEqual({ value: 1 });
-    add();
-    expect(store.use(countModel)[0]).toEqual({ value: 2 });
-  });
-});
-```
-:::info
-The [`createStore`](/apis/app/runtime/model/create-store) used here is imported from `@modern-js/runtime/testing`, which internally uses the configuration of [`runtime.state`](/configure/app/runtime/state) to create a `store`.
-:::
-In the test case, we create a new `store` to mount `countModel`, use `store.use` to get the State and Actions of `countModel`. Then, we call the `add` Action to update the state and assert the updated state value.
-Execute the `pnpm run test` command to trigger the execution of the test case.

package/docs/zh/apis/app/runtime/testing/_category_.json DELETED Viewed

@@ -1,4 +0,0 @@
-{
-  "label": "Testing",
-  "position": 11
-}

package/docs/zh/apis/app/runtime/testing/act.mdx DELETED Viewed

@@ -1,35 +0,0 @@
----
-title: act
----
-# act
-用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
-## 使用姿势
-```ts
-import { act } from '@modern-js/runtime/testing';
-```
-## 函数签名
-`act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
-## 示例
-```tsx
-import ReactDOM from 'react-dom';
-import { act } from '@modern-js/runtime/testing';
-import { Foo } from '@/components/Foo';
-describe('test act', () => {
-  it('it should be foo', () => {
-    const el = document.createElement('div');
-    act(() => {
-      ReactDOM.render(<Foo />, el);
-    });
-    expect(el.innerHTML).toBe('<div>Foo</div>');
-  });
-});
-```

package/docs/zh/apis/app/runtime/testing/cleanup.mdx DELETED Viewed

@@ -1,40 +0,0 @@
----
-title: cleanup
-sidebar_position: 3
----
-# cleanup
-用于卸载掉当前已渲染的所有组件。
-## 使用姿势
-```ts
-import { cleanup } from '@modenr-js/runtime/testing';
-```
-## 函数签名
-`function cleanup(): void`
-## 示例
-:::info
-请注意，如果你使用的测试框架支持 afterEach，并且它被注入到你的测试环境中（如 mocha、Jest 和 Jasmine），**会默认在 afterEach 钩子里执行 `cleanup`**。否则，你将需要在每次测试后进行手动清理。
-:::
-例如，如果你使用[ava](https://github.com/avajs/ava)测试框架，那么你需要像这样使用 test.afterEach 钩子。
-```tsx
-import { cleanup, render } from '@modern-js/runtime/testing';
-import test from 'ava';
-test.afterEach(cleanup);
-test('renders into document', () => {
-  render(<div />);
-  // ...
-});
-// ... more tests ...
-```