236 lines
4.9 KiB
Markdown
236 lines
4.9 KiB
Markdown
|
# 贡献指南
|
|||
|
|
|
|||
|
|
感谢您对 AIOT 项目的兴趣！本指南将帮助您有效地为项目做出贡献。
|
|||
|
|
|
|||
|
|
## 🚀 开始贡献
|
|||
|
|
|
|||
|
|
### 第一步：设置开发环境
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 克隆仓库
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 第二步：阅读编码规范
|
|||
|
|
|
|||
|
|
- [代码风格指南](10-standards/01-code-style.md)
|
|||
|
|
- [命名规范](10-standards/02-naming-conventions.md)
|
|||
|
|
- [Git 工作流](10-standards/03-git-workflow.md)
|
|||
|
|
- [Commit 信息规范](10-standards/04-commit-messages.md)
|
|||
|
|
|
|||
|
|
### 第三步：创建 Feature 分支
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git checkout -b feature/your-feature-name
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 第四步：编写代码和测试
|
|||
|
|
|
|||
|
|
- 遵循编码规范
|
|||
|
|
- 添加单元测试
|
|||
|
|
- 确保测试通过
|
|||
|
|
|
|||
|
|
### 第五步：提交 Pull Request
|
|||
|
|
|
|||
|
|
详见：[代码审查流程](10-standards/05-code-review.md)
|
|||
|
|
|
|||
|
|
## 📋 贡献类型
|
|||
|
|
|
|||
|
|
### 🐛 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](https://www.conventionalcommits.org/) 规范：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
<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. 合并到主分支
|
|||
|
|
|
|||
|
|
详见：[代码审查指南](10-standards/05-code-review.md)
|
|||
|
|
|
|||
|
|
## 🧪 测试要求
|
|||
|
|
|
|||
|
|
### 单元测试
|
|||
|
|
- 所有新功能必须有单元测试
|
|||
|
|
- 目标覆盖率：80%+
|
|||
|
|
- 测试应该是独立的和快速的
|
|||
|
|
|
|||
|
|
### 集成测试
|
|||
|
|
- 跨服务交互必须有集成测试
|
|||
|
|
- 数据库操作需要测试
|
|||
|
|
|
|||
|
|
### 端到端测试（E2E）
|
|||
|
|
- 关键用户流程必须有 E2E 测试
|
|||
|
|
- 使用 Selenium/Cypress（前端）或 Appium（移动）
|
|||
|
|
|
|||
|
|
### 性能测试
|
|||
|
|
- 关键路径的性能基准
|
|||
|
|
- 监控性能回归
|
|||
|
|
|
|||
|
|
详见各端的测试指南：
|
|||
|
|
- [后端测试](03-backend/09-testing.md)
|
|||
|
|
- [前端测试](04-frontend/10-testing.md)
|
|||
|
|
- [移动测试](05-mobile/11-testing.md)
|
|||
|
|
|
|||
|
|
## 📚 文档要求
|
|||
|
|
|
|||
|
|
### 代码注释
|
|||
|
|
- 复杂逻辑需要注释
|
|||
|
|
- 函数应该有 JSDoc/docstring
|
|||
|
|
- 解释 *为什么*，不是 *什么*
|
|||
|
|
|
|||
|
|
### API 文档
|
|||
|
|
- 新端点需要 OpenAPI/Swagger 文档
|
|||
|
|
- 包括请求/响应示例
|
|||
|
|
|
|||
|
|
### README
|
|||
|
|
- 新功能应该在 README 中提及
|
|||
|
|
- 更新相关文档
|
|||
|
|
|
|||
|
|
### 更新日志
|
|||
|
|
- 在 CHANGELOG.md 中记录重要变更
|
|||
|
|
- 按版本组织
|
|||
|
|
|
|||
|
|
## 🚨 安全考虑
|
|||
|
|
|
|||
|
|
提交包含以下内容的 PR 时，请特别小心：
|
|||
|
|
|
|||
|
|
- [ ] 用户输入验证
|
|||
|
|
- [ ] SQL 注入防护
|
|||
|
|
- [ ] 跨站脚本（XSS）防护
|
|||
|
|
- [ ] 跨站请求伪造（CSRF）防护
|
|||
|
|
- [ ] 认证和授权检查
|
|||
|
|
- [ ] 敏感数据加密
|
|||
|
|
|
|||
|
|
详见：[安全检查清单](11-guides/04-security-checklist.md)
|
|||
|
|
|
|||
|
|
## 💬 沟通和讨论
|
|||
|
|
|
|||
|
|
### GitHub Discussions
|
|||
|
|
- 功能建议
|
|||
|
|
- 架构讨论
|
|||
|
|
- 最佳实践分享
|
|||
|
|
|
|||
|
|
### Issues
|
|||
|
|
- Bug 报告
|
|||
|
|
- 功能请求
|
|||
|
|
- 任务跟踪
|
|||
|
|
|
|||
|
|
### 其他沟通
|
|||
|
|
- 项目 Slack 频道
|
|||
|
|
- 定期团队会议
|
|||
|
|
|
|||
|
|
## 🏆 贡献者荣誉
|
|||
|
|
|
|||
|
|
我们感谢所有贡献者！在以下地方获得认可：
|
|||
|
|
- CONTRIBUTORS.md 文件
|
|||
|
|
- GitHub Contributors 页面
|
|||
|
|
- 项目网站
|
|||
|
|
|
|||
|
|
## ❓ 有问题？
|
|||
|
|
|
|||
|
|
- 查看 [FAQ](../13-faq/general.md)
|
|||
|
|
- 提交 GitHub Issue
|
|||
|
|
- 联系项目维护者
|
|||
|
|
- 加入项目社区
|
|||
|
|
|
|||
|
|
## 📖 更多资源
|
|||
|
|
|
|||
|
|
- [开发指南](DEVELOPMENT.md)
|
|||
|
|
- [Git 工作流详解](10-standards/03-git-workflow.md)
|
|||
|
|
- [架构文档](ARCHITECTURE.md)
|
|||
|
|
- [各端开发指南](01-getting-started/)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**感谢您的贡献！** 🎉
|
|||
|
|
|
|||
|
|
我们期待看到您的代码、想法和改进！
|