#贡献指南

本文帮助你快速在本仓库完成开发、测试与提 PR。仓库采用 Rush + pnpm 的 Monorepo 管理方式，文档站基于 Rspress 构建。

#构建开发环境

1. 安装 Node.js 18+（推荐 LTS/Hydrogen）

nvm install lts/hydrogen
nvm alias default lts/hydrogen # 设为默认 Node 版本
nvm use lts/hydrogen

2. 克隆仓库到本地

git clone git@github.com:bytedance/flowgram.ai.git

3. 安装全局依赖

npm i -g pnpm@10.6.5 @microsoft/rush@5.150.0

4. 安装项目依赖

rush install

5. 构建项目

rush build

6. 运行文档或示例

rush dev:docs                  # 在 apps/docs 启动文档站（含增量构建）
rush dev:demo-fixed-layout     # 运行固定布局示例
rush dev:demo-free-layout      # 运行自由布局示例

#常用命令（Rush 自定义）

rush build            # 构建所有包
rush build:watch      # 增量构建并监听
rush lint             # 运行 ESLint 检查
rush lint:fix         # 自动修复 ESLint 问题
rush ts-check         # TypeScript 类型检查
rush test             # 运行各包的测试脚本（按包聚合）
rush e2e:test         # 运行所有 e2e 测试
rush e2e:update-screenshot # 更新 e2e 快照
rush dep-check        # 自动检查依赖健康度

#分支与提交规范

• 分支命名：
  • feat/描述（新功能）
  • fix/描述（问题修复）
  • docs/描述（文档变更）
  • chore/描述（维护/杂项）
• 提交信息（Conventional Commits）：
  • 格式：type(scope): subject，例如：

feat(editor): 支持节点批量对齐

• 常用类型：feat、fix、docs、style、refactor、test、chore
• 仓库已启用 commitlint 校验（commit-msg 钩子），提交信息将被自动检查；同时 pre-commit 会运行 lint-staged（自动更新许可证头、eslint 修复）与 rush check 校验。

#开发与质量保障

• 本地开发建议：
  • 先执行 rush build:watch，再在对应 demo 或 docs 目录运行开发命令（如 rush dev:docs）。
  • 修改代码后，确保通过：rush lint、rush ts-check、rush build、rush test。
• 测试说明：
  • e2e 用例位于 e2e/ 目录，可通过 rush e2e:test 运行，或更新快照 rush e2e:update-screenshot。

#Pull Request 流程

1. 从 main 创建你的工作分支（遵循分支命名规范）。
2. 编码并补充测试/文档。
3. 本地通过质量校验（lint、ts-check、build、test）。
4. 提交 PR：填写说明、关联 Issue，并注意使用模板。
5. 评审与 CI：维护者会进行代码评审，CI 全绿后即可合并。

#文档贡献

• 文档位置：apps/docs/src/zh/**（中文）与 apps/docs/src/en/**（英文）。
• 本地预览：执行 rush dev:docs 启动 Rspress 文档站。
• 若需自动生成 API 文档，可在 apps/docs 目录执行 rushx docs（调用脚本生成）。

#常见问题

• pnpm-lock 合并冲突：仓库已在 post-checkout 钩子中配置合并策略，通常可避免锁文件冲突。
• Node 版本：请确保使用 Node 18+，否则可能出现依赖或构建失败。

#报告问题

• 请在 GitHub 提交 Issue：https://github.com/bytedance/flowgram.ai/issues/new/choose
  • 描述问题、复现步骤、期望与实际行为，必要时附代码示例。

#许可证

• 本项目遵循 MIT 许可证。提交代码即默认同意相关条款。