XW-AIOT/aiot-document
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c71e8d31cf8aff7a581b2791dd68c441282bf2e4
aiot-document/CONTRIBUTING.md
lzh 0b645c72fc docs: 修复导航与架构文档中的错误引用 
- 00-阅读地图：修正协作规范文档路径
- 01-总体架构设计：修正引用路径

第二轮迭代审阅中...
2026-04-07 13:59:14 +08:00

4.9 KiB
Raw Blame History

贡献指南

感谢您对 AIOT 项目的兴趣！本指南将帮助您有效地为项目做出贡献。

🚀 开始贡献

第一步：设置开发环境

# 克隆仓库
git clone https://github.com/your-org/aiot.git
cd aiot

# 按照你的端的指南配置环境
# 后端：docs/03-backend/01-setup.md
# 前端：docs/04-frontend/01-setup.md
# 移动：docs/05-mobile/01-setup.md

第二步：阅读编码规范

第三步：创建 Feature 分支

git checkout -b feature/your-feature-name

第四步：编写代码和测试

  • 遵循编码规范
  • 添加单元测试
  • 确保测试通过

第五步：提交 Pull Request

详见：代码审查流程

📋 贡献类型

🐛 Bug 修复

  1. 创建 Issue 描述 Bug
  2. Fork 仓库
  3. 创建修复分支：git checkout -b fix/issue-number
  4. 提交 PR，引用 Issue

✨ 新功能

  1. 讨论功能设计（创建 Discussion 或 Issue）
  2. Fork 仓库
  3. 创建功能分支：git checkout -b feature/feature-name
  4. 提交 PR 描述功能和测试

📖 文档改进

  1. 编辑相关 Markdown 文件
  2. 提交 PR
  3. 使用 Preview 功能检查格式

🎨 UI/UX 改进

  1. 在 Issue 中提出建议（包括设计稿）
  2. 讨论和反馈
  3. 实现并提交 PR

📝 Commit 信息规范

遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型（type）

  • feat — 新功能
  • fix — 错误修复
  • docs — 文档改进
  • style — 代码风格（不影响功能）
  • refactor — 代码重构
  • perf — 性能优化
  • test — 测试相关
  • chore — 构建、依赖等

范围（scope）

  • backend — 后端
  • frontend — 前端
  • mobile — 移动端
  • device — 设备相关
  • docs — 文档
  • infra — 基础设施

例子

feat(backend): add device real-time status updates via WebSocket

- Implement WebSocket server for real-time device status
- Add subscription management for device changes
- Add reconnection logic with exponential backoff

Fixes #123

✅ Pull Request 检查清单

在提交 PR 前，请确保：

  • 代码遵循项目编码规范
  • 添加了必要的测试
  • 所有测试通过
  • 更新了相关文档
  • Commit 信息清晰明了
  • 没有 merge 冲突
  • 代码审查无重大问题

🔍 代码审查

审查标准

  • 代码质量和可维护性
  • 测试覆盖率
  • 性能影响
  • 安全考虑
  • API 设计一致性

审查流程

  1. 至少一位维护者审查
  2. 全部对话解决
  3. 至少一个 Approve
  4. CI/CD 通过
  5. 合并到主分支

详见：代码审查指南

🧪 测试要求

单元测试

  • 所有新功能必须有单元测试
  • 目标覆盖率：80%+
  • 测试应该是独立的和快速的

集成测试

  • 跨服务交互必须有集成测试
  • 数据库操作需要测试

端到端测试（E2E）

  • 关键用户流程必须有 E2E 测试
  • 使用 Selenium/Cypress（前端）或 Appium（移动）

性能测试

  • 关键路径的性能基准
  • 监控性能回归

详见各端的测试指南：

📚 文档要求

代码注释

  • 复杂逻辑需要注释
  • 函数应该有 JSDoc/docstring
  • 解释 为什么，不是 什么

API 文档

  • 新端点需要 OpenAPI/Swagger 文档
  • 包括请求/响应示例

README

  • 新功能应该在 README 中提及
  • 更新相关文档

更新日志

  • 在 CHANGELOG.md 中记录重要变更
  • 按版本组织

🚨 安全考虑

提交包含以下内容的 PR 时，请特别小心：

  • 用户输入验证
  • SQL 注入防护
  • 跨站脚本（XSS）防护
  • 跨站请求伪造（CSRF）防护
  • 认证和授权检查
  • 敏感数据加密

详见：安全检查清单

💬 沟通和讨论

GitHub Discussions

  • 功能建议
  • 架构讨论
  • 最佳实践分享

Issues

  • Bug 报告
  • 功能请求
  • 任务跟踪

其他沟通

  • 项目 Slack 频道
  • 定期团队会议

🏆 贡献者荣誉

我们感谢所有贡献者！在以下地方获得认可：

  • CONTRIBUTORS.md 文件
  • GitHub Contributors 页面
  • 项目网站

❓ 有问题？

  • 查看 FAQ
  • 提交 GitHub Issue
  • 联系项目维护者
  • 加入项目社区

📖 更多资源

感谢您的贡献！ 🎉

我们期待看到您的代码、想法和改进！