diff --git a/website/docs/en/guide/upgrade/v1-to-v2.mdx b/website/docs/en/guide/upgrade/v1-to-v2.mdx
index 5310ab89ed..453a911c42 100644
--- a/website/docs/en/guide/upgrade/v1-to-v2.mdx
+++ b/website/docs/en/guide/upgrade/v1-to-v2.mdx
@@ -231,3 +231,32 @@ The specific changes are as follows:
 - Removed the `api.modifyWebpackChain` and `api.modifyWebpackConfig` plugin hooks.
 - Removed the `webpack` type from the `api.context.bundlerType`.
 - Removed webpack-related types.
+
+## Built-in rule changes
+
+The built-in JS and CSS transform rules now use [oneOf](https://rspack.rs/config/module-rules#rulesoneof) to separate different branches. If you customized the JS or CSS rules with [tools.bundlerChain](/config/tools/bundler-chain#toolsbundlerchain) or [api.modifyBundlerChain](/plugins/dev/hooks#modifybundlerchain), you may need to adjust your configuration.
+
+### JavaScript rule
+
+The built-in JS rule is now split into two `oneOf` branches:
+
+- `CHAIN_ID.ONE_OF.JS_TRANSFORM`: for SWC transforms
+- `CHAIN_ID.ONE_OF.JS_RAW`: for `?raw` imports
+
+If you previously added loaders on `CHAIN_ID.RULE.JS`, move them to the corresponding `oneOf` branch:
+
+```diff title="rsbuild.config.ts"
+export default {
+  tools: {
+    bundlerChain(chain, { CHAIN_ID }) {
+      const jsRule = chain.module.rule(CHAIN_ID.RULE.JS);
+
+-     jsRule.use('my-loader').loader('my-loader');
++     jsRule
++       .oneOf(CHAIN_ID.ONE_OF.JS_TRANSFORM)
++       .use('my-loader')
++       .loader('my-loader');
+    },
+  },
+};
+```
diff --git a/website/docs/zh/guide/upgrade/v1-to-v2.mdx b/website/docs/zh/guide/upgrade/v1-to-v2.mdx
index 433f758741..a22296f5b9 100644
--- a/website/docs/zh/guide/upgrade/v1-to-v2.mdx
+++ b/website/docs/zh/guide/upgrade/v1-to-v2.mdx
@@ -231,3 +231,32 @@ Rsbuild 2.0 不再支持使用 webpack 作为打包工具。在 Rsbuild 1.x 版
 - 移除 `api.modifyWebpackChain` 和 `api.modifyWebpackConfig` 插件钩子。
 - 移除 `api.context.bundlerType` 中的 `webpack` 类型。
 - 移除 webpack 相关的类型。
+
+## 内置规则变化
+
+Rsbuild 内置的 JS 和 CSS 转换规则现在使用了 [oneOf](https://rspack.rs/config/module-rules#rulesoneof) 来区分不同的分支，如果你使用 [tools.bundlerChain](/config/tools/bundler-chain#toolsbundlerchain) 或 [api.modifyBundlerChain](/plugins/dev/hooks#modifybundlerchain) 修改了 JS 或 CSS 规则，可能需要进行相应调整。
+
+### JS 规则
+
+内置 JS 规则现在拆分为两个 `oneOf` 分支：
+
+- `CHAIN_ID.ONE_OF.JS_TRANSFORM`：用于 SWC 转换
+- `CHAIN_ID.ONE_OF.JS_RAW`：用于处理 `?raw` 导入
+
+如果你之前在 `CHAIN_ID.RULE.JS` 上添加 loader，现在需要改为在对应的 `oneOf` 上配置：
+
+```diff title="rsbuild.config.ts"
+export default {
+  tools: {
+    bundlerChain(chain, { CHAIN_ID }) {
+      const jsRule = chain.module.rule(CHAIN_ID.RULE.JS);
+
+-     jsRule.use('my-loader').loader('my-loader');
++     jsRule
++       .oneOf(CHAIN_ID.ONE_OF.JS_TRANSFORM)
++       .use('my-loader')
++       .loader('my-loader');
+    },
+  },
+};
+```