Skip to content

Contributing

Jump to bottom
李源炳 edited this page Jun 19, 2026 · 1 revision

贡献指南

欢迎来到 IMBoy！我们秉承开源精神，欢迎任何形式的贡献：代码、文档、测试、Bug 报告、功能建议。

开始之前

  1. 阅读 快速开始 搭建本地开发环境
  2. 浏览 GitHub Issues 了解当前优先级
  3. 查看各仓库的 CLAUDE.md 了解架构规范

仓库分工

仓库 语言 职责
imboy Erlang/OTP 后端主服务
imboyapp Flutter/Dart iOS/Android 移动端
imboy-admin-frontend React/TypeScript Web 管理后台
imboy-sdk-js TypeScript JS/TS 客户端 SDK
erlang_migrate Erlang 数据库迁移库

贡献流程

1. Fork & Clone

# Fork 仓库后 clone 你的 Fork
git clone https://github.com/<your-username>/imboy.git
cd imboy

# 添加上游远程
git remote add upstream https://github.com/imboy-pub/imboy.git

2. 创建分支

git checkout -b feat/your-feature-name
# 或
git checkout -b fix/issue-123-description

分支命名规范：feat/、fix/、docs/、test/、refactor/

3. 开发

遵循以下原则：

  • 函数 < 50 行，文件 < 800 行
  • 先写测试（TDD），然后实现
  • 不可变数据：创建新对象，不原地修改
  • 分层边界（后端）：Handler → Logic → DS → Repo，单向依赖，禁止跨层调用
  • 所有 SQL 必须参数化，禁止字符串拼接

4. 提交

提交消息遵循 Conventional Commits：

<type>: <description>

[optional body]

类型：feat / fix / refactor / docs / test / chore / perf

示例：

feat: add group announcement feature
fix: resolve WebSocket reconnect loop on iOS 17
docs: update E2EE setup instructions

所有提交必须签署 DCO（Developer Certificate of Origin）：

git commit -s -m "feat: your feature"

5. 测试

提交前确保测试通过：

# 后端（Erlang）
make eunit
make dialyze

# 移动端（Flutter）
flutter test
flutter analyze

# 管理后台（React）
bun test
bun run lint

覆盖率要求：Repo 层 80%+，Logic 层 70%+。

6. 提交 Pull Request

git push origin feat/your-feature-name

在 GitHub 上创建 PR，填写：

  • 变更说明（是什么、为什么）
  • 测试方案
  • 截图（UI 变更时）

PR 会由维护者审查，通常在 3 个工作日内响应。

代码规范

后端（Erlang）

  • 遵循 OTP 设计原则
  • 使用 erlfmt 格式化（pre-commit hook 自动检查）
  • 错误统一用 {error, {Code, Msg}} 格式返回
  • 新 API 端点：handler → router → logic → EUnit 测试

移动端（Flutter/Dart）

  • 颜色用 AppColors，间距用 AppSpacing，字号用 FontSizeType
  • 禁止硬编码颜色值、字号、间距
  • 路由通过 go_router 管理
  • 附件 URL 必须经 AssetsService.viewUrl 授权

管理后台（React/TypeScript）

  • 严格类型，禁止 any
  • 服务端状态用 TanStack Query，客户端状态用 Zustand
  • 64-bit ID 用 EntityId 类型，不用 string / number

报告 Bug

在 GitHub Issues 中使用 Bug 模板，包含：

  1. 环境信息（OS、版本、部署方式）
  2. 复现步骤
  3. 预期行为 vs 实际行为
  4. 相关日志

功能建议

在 GitHub Issues 中使用 Feature Request 模板。请说明使用场景（why），而不仅仅是功能描述（what）。

行为准则

我们遵守 Contributor Covenant 行为准则。请在所有社区交流中保持尊重和包容。

联系维护者

Clone this wiki locally