docs: 更新开发指南到 bun 栈 (#485)

Author: Linho1219

packages/docs/src/content/docs/contribute/development/environments.md

@@ -4,24 +4,24 @@ title: 开发环境配置
 
 ## 必要环境
 
-- Node.js 22+（[官网](https://nodejs.org/)）
-- bun（[官网](https://bun.sh/)）
+- bun（[官网](https://bun.sh/)），建议版本与仓库 `package.json` 中 `packageManager` 一致（当前为 `bun@1.3.12`）
 - Rust toolchain（[官网](https://www.rust-lang.org/tools/install)）
 - Rust target：`wasm32-unknown-unknown`。
 - wasm-pack（[仓库](https://github.com/rustwasm/wasm-pack)）
 
-另外，建议全局安装 Nx。全局安装后 Nx 相关命令直接为 `nx ...`，否则使用 `bunx nx ...`。此后不再赘述。
+本仓库默认使用 `bun nx ...` 执行 Nx 命令，不要求全局安装 Nx。为了本地便利开发，你也可以全局安装 Nx，效果是相同的。
+
+Node.js 仅在 npm 发布相关 CI 步骤中作为运行时使用（当前发布工作流为 Node 24）。
 
 ### 版本自查
 
 ```bash
-node --version
 bun --version
 rustc --version
 cargo --version
 rustup --version
 wasm-pack --version
-nx --version
+nx --version # 可选
 ```
 
 如需确认 wasm 目标已安装，可额外执行：
@@ -45,22 +45,6 @@ cargo install wasm-pack
 
 完成后，执行一次构建所有包：`bun run build:libs`，若成功构建完成说明环境无误，可以开始工作。
 
-## 本地开发常用命令
-
-```bash
-# 构建所有 library
-bun run build:libs
-
-# 构建某个包
-nx build core
-
-# 仅启动文档站
-nx dev docs
-
-# 构建文档站
-nx build docs
-```
-
 ## 与 Rust/WASM 相关的包
 
 以下包使用 `wasm-pack` 构建：
@@ -87,7 +71,7 @@ rustup target add wasm32-unknown-unknown
 
 ### 依赖安装慢或失败
 
-优先确认 Node/bun 版本与锁文件一致，再重试：
+优先确认 Bun 版本与锁文件一致，再重试：
 
 ```bash
 bun install --frozen-lockfile

packages/docs/src/content/docs/contribute/development/structure.mdx

@@ -11,39 +11,96 @@ import { FileTree } from "@astrojs/starlight/components";
 <FileTree>
 
 - packages/
-  - core/
-  - react/
-  - react-full/
-  - vue/
-  - lyric/ Rust + wasm-pack
+  - core/ 核心组件，Vanilla JS 实现
+  - react/ 核心组件的 React 绑定
+  - vue/ 核心组件的 Vue 绑定
+  - react-full/ 可直接使用的完整播放器组件，仅 React 版本
+  - ttml/ TTML 解析与处理库
+  - lyric/ 歌词解析与处理库，TTML 实际依赖 ttml 包
   - fft/ Rust + wasm-pack
   - ws-protocol/ Rust + wasm-pack
-  - ttml/
   - docs/ Astro + Starlight 文档站
+  - playground/ 用于开发和测试的示例项目
+    - core/ 使用核心组件的示例
+    - react/ 使用 React 绑定的示例
+    - vue/ 使用 Vue 绑定的示例
+    - react-full/ 使用完整播放器组件的示例
 - .github/
   - workflows/
-- nx.json
+  - scripts/
 
 </FileTree>
 
-## 包分层（概览）
-
-- 渲染与框架绑定：`core`、`react`、`react-full`、`vue`
-- 歌词与协议能力：`lyric`、`ttml`、`ws-protocol`
-- 音频可视化：`fft`
-- 文档站：`docs`
-
-## Nx 与发布分组
+## Nx 发布分组
 
 `nx.json` 中的发布配置包含两个主要 group：
 
-- `core-bundle`（固定版本）：
+- `core-bundle` 三个包版本保持一致：
   - `@applemusic-like-lyrics/core`
   - `@applemusic-like-lyrics/react`
   - `@applemusic-like-lyrics/vue`
-- `libraries`（独立版本）：
+- 其余包版本各自独立：
   - `@applemusic-like-lyrics/fft`
   - `@applemusic-like-lyrics/lyric`
   - `@applemusic-like-lyrics/react-full`
   - `@applemusic-like-lyrics/ttml`
   - `@applemusic-like-lyrics/ws-protocol`
+
+## 依赖关系
+
+你可以在终端执行：
+
+```sh
+bun nx graph
+```
+
+来查看完整的依赖关系图。
+
+在提升版本号时，如果被依赖的包发生了更新，则依赖它的包也会被自动提升版本号，即使代码没有改动。
+
+## 命令行
+
+### 库开发
+
+Nx 提供了便捷的命令行工具，无需输入 `@applemusic-like-lyrics/` 前缀也可执行命令。
+
+例如，要构建 `@applemusic-like-lyrics/react` 包，可以直接执行：
+
+```sh
+bun nx build react
+```
+
+Nx 会自动解析依赖，因此会先构建 `core` 包，然后构建 `react` 包。
+
+我们在 `package/playground` 中准备了用于测试的 web app，基于 Vite，具有 HMR 支持。我们从 `core`、`react`、`vue`、`react-full` 中添加了转发，因此要启动对应环境，只需要：
+
+```sh
+# 启动 package/playground/core 的开发服务器
+bun nx dev core
+
+# 下面同理
+bun nx dev react
+bun nx dev vue
+bun nx dev react-full
+```
+
+要构建全部包，执行：
+
+```sh
+bun build:libs
+```
+
+即可自动并行构建所有包，构建顺序由依赖关系决定。
+
+### 文档开发
+
+同理，文档站的别名是 `docs`，有如下命令：
+
+```sh
+# 启动文档站开发服务器
+bun nx dev docs
+# 构建文档站
+bun nx build docs
+```
+
+会自动处理依赖关系。

packages/docs/src/content/docs/contribute/guidelines/pr.md

@@ -17,7 +17,7 @@ title: PR 流程
   - 在需要时执行 `bun run release:plan:check --base=... --head=...`。
 
 2. `Build libs`
-  - 安装 Node/Bun 依赖。
+  - 安装 Bun 依赖（`bun install --frozen-lockfile`）。
   - 安装 Rust `stable`、`wasm32-unknown-unknown`、`wasm-pack@v0.13.1`。
   - 执行 `bun run ci:build:libs`。
 
@@ -35,9 +35,13 @@ title: PR 流程
 
 ```bash
 # 只为本次 touched 项目生成计划（默认行为）
-nx release plan
+bun nx release plan
 ```
 
 然后根据提示选择各包变动幅度并输入 changelog。
 
 命令会在 `.nx/version-plans/` 下生成计划文件，请将该文件一并提交。
+
+## 关于合并
+
+目前设置了分支保护规则，仅允许 squash merge，以保持主分支洁净。

packages/docs/src/content/docs/contribute/guidelines/publishing.md

@@ -15,27 +15,24 @@ npm 包发布通过 GitHub Actions 手动触发，工作流文件：
 
 ## 发布前置条件
 
-- 必须从 `main` 分支触发（工作流内有强校验）。
+- `publish` 必须从 `main` 分支触发，`dry-run` 可以从其他分支触发。
 - `.nx/version-plans/` 下必须存在 release plan 文件。
-- 仓库 PR 校验应已通过。
 
 ## 工作流执行步骤摘要
 
-1. 校验当前分支是 `main`。
-2. 安装依赖与发布环境（Node 24、Bun、Rust、wasm-pack）。
-3. 执行 `bunx nx release --dry-run`。
-4. 当 `mode=publish` 时：
-  - 执行 `bunx nx release --skip-publish` 创建 release commit 与 tags。
+1. 当 `mode=publish` 时，强校验当前分支必须是 `main`。
+2. 安装依赖与发布环境（Bun、Node 24、Rust、wasm-pack）。
+3. 校验 trusted publishing 运行时（Node 版本等）。
+4. 执行 `bun install --frozen-lockfile`。
+5. 执行 `npx nx release --skip-publish --preid alpha` 创建 release commit 与 tags。
+6. 格式化 `package.json` 并 amend release commit。
+7. 当 `mode=publish` 时：
   - `git push origin HEAD:main --follow-tags`。
-  - 执行 `bunx nx release publish` 发布到 npm。
+  - 调整发布前清单（强制 npm 发布器、准备 npm manifests）。
+  - 执行 `npx nx release publish --excludeTaskDependencies` 发布到 npm。
 
 ## 推荐发布流程
 
-1. 先手动触发一次 `mode=dry-run`，确认版本变更和产物正常。
+1. 先手动触发一次 `mode=dry-run`，确认版本变更与发布前检查正常（该模式不会推送 tags，也不会发布到 npm）。
 2. 再触发 `mode=publish` 完成正式发布。
 3. 发布后检查 npm 与 GitHub tags 是否符合预期。
-
-## 注意事项
-
-- 本仓库使用 Nx release groups，部分包是固定版本（如 `core-bundle`），部分包是独立版本（`libraries`）。
-- 发布流程依赖 OIDC trusted publishing 运行时要求，工作流已内置 Node/NPM 版本校验。