306 lines
4.4 KiB
Markdown
306 lines
4.4 KiB
Markdown
# 贡献指南
|
|
|
|
感谢你对小虾 SaaS 项目的兴趣！
|
|
|
|
## 🚀 快速开始
|
|
|
|
### 1. Fork 和克隆
|
|
|
|
```bash
|
|
# Fork 项目到你的账号
|
|
# 然后克隆
|
|
git clone https://github.com/your-username/xiaoxia-saas.git
|
|
cd xiaoxia-saas
|
|
```
|
|
|
|
### 2. 设置开发环境
|
|
|
|
```bash
|
|
# 创建虚拟环境
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/Mac
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# 安装依赖
|
|
pip install -r requirements.txt
|
|
|
|
# 使用内存数据库（无需 PostgreSQL）
|
|
echo "USE_IN_MEMORY_DB=true" > .env
|
|
|
|
# 启动开发服务器
|
|
uvicorn apps.api.main:app --reload
|
|
```
|
|
|
|
### 3. 运行测试
|
|
|
|
```bash
|
|
# 运行所有测试
|
|
pytest tests/ -v
|
|
|
|
# 运行单元测试
|
|
pytest tests/unit -v
|
|
|
|
# 生成覆盖率报告
|
|
pytest --cov=packages --cov-report=html
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 提交规范
|
|
|
|
### Commit Message 格式
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
**Type:**
|
|
- `feat`: 新功能
|
|
- `fix`: Bug 修复
|
|
- `docs`: 文档更新
|
|
- `style`: 代码格式（不影响功能）
|
|
- `refactor`: 重构
|
|
- `test`: 测试相关
|
|
- `chore`: 构建/工具相关
|
|
|
|
**示例:**
|
|
```
|
|
feat(auth): add password reset functionality
|
|
|
|
- Add RequestPasswordResetUseCase
|
|
- Send reset email with token
|
|
- Implement ResetPasswordUseCase
|
|
- Add unit tests
|
|
|
|
Closes #123
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ 代码规范
|
|
|
|
### Python 代码风格
|
|
|
|
- 遵循 PEP 8
|
|
- 使用类型注解
|
|
- 函数和类添加 docstring
|
|
- 每个文件顶部添加模块说明
|
|
|
|
### 代码格式化
|
|
|
|
```bash
|
|
# 安装工具
|
|
pip install black isort
|
|
|
|
# 格式化代码
|
|
black packages/ apps/ tests/
|
|
isort packages/ apps/ tests/
|
|
```
|
|
|
|
### 架构原则
|
|
|
|
- 遵循 Clean Architecture
|
|
- 业务逻辑在 Application 层
|
|
- 基础设施在 Adapters 层
|
|
- 保持层次间依赖方向正确
|
|
|
|
---
|
|
|
|
## 🧪 测试要求
|
|
|
|
### 单元测试
|
|
|
|
- 所有新功能必须有单元测试
|
|
- 测试覆盖率不低于 80%
|
|
- 使用 pytest fixtures
|
|
- Mock 外部依赖
|
|
|
|
### 测试示例
|
|
|
|
```python
|
|
def test_create_workspace_success(use_case, mock_repo):
|
|
\"\"\"测试创建工作空间成功\"\"\"
|
|
request = CreateWorkspaceRequest(
|
|
name="Test",
|
|
owner_user_id="user-123",
|
|
)
|
|
|
|
response, error = use_case.execute(request)
|
|
|
|
assert error is None
|
|
assert response.name == "Test"
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Pull Request 流程
|
|
|
|
### 1. 创建分支
|
|
|
|
```bash
|
|
# 从 main 创建功能分支
|
|
git checkout -b feat/your-feature-name
|
|
```
|
|
|
|
### 2. 开发和测试
|
|
|
|
```bash
|
|
# 编写代码
|
|
# 运行测试
|
|
pytest tests/ -v
|
|
|
|
# 提交
|
|
git add .
|
|
git commit -m "feat: your feature description"
|
|
```
|
|
|
|
### 3. 推送和创建 PR
|
|
|
|
```bash
|
|
# 推送到你的 fork
|
|
git push origin feat/your-feature-name
|
|
|
|
# 在 GitHub 上创建 Pull Request
|
|
```
|
|
|
|
### 4. PR 描述模板
|
|
|
|
```markdown
|
|
## 变更说明
|
|
简要描述此 PR 的目的
|
|
|
|
## 变更类型
|
|
- [ ] 新功能
|
|
- [ ] Bug 修复
|
|
- [ ] 文档更新
|
|
- [ ] 重构
|
|
- [ ] 其他
|
|
|
|
## 测试
|
|
- [ ] 添加了单元测试
|
|
- [ ] 所有测试通过
|
|
- [ ] 手动测试通过
|
|
|
|
## 截图（如适用）
|
|
添加相关截图
|
|
|
|
## 相关 Issue
|
|
Closes #issue_number
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 报告 Bug
|
|
|
|
### Bug 报告模板
|
|
|
|
```markdown
|
|
**描述**
|
|
清晰描述 bug
|
|
|
|
**复现步骤**
|
|
1. 进入 '...'
|
|
2. 点击 '...'
|
|
3. 滚动到 '...'
|
|
4. 看到错误
|
|
|
|
**期望行为**
|
|
描述期望发生什么
|
|
|
|
**实际行为**
|
|
描述实际发生了什么
|
|
|
|
**环境**
|
|
- OS: [e.g. Ubuntu 22.04]
|
|
- Python: [e.g. 3.12]
|
|
- 浏览器: [e.g. Chrome 120]
|
|
|
|
**额外信息**
|
|
添加任何其他相关信息
|
|
```
|
|
|
|
---
|
|
|
|
## 💡 功能建议
|
|
|
|
### 功能请求模板
|
|
|
|
```markdown
|
|
**功能描述**
|
|
简要描述建议的功能
|
|
|
|
**问题**
|
|
此功能解决什么问题？
|
|
|
|
**建议方案**
|
|
描述你期望的解决方案
|
|
|
|
**替代方案**
|
|
考虑过哪些替代方案？
|
|
|
|
**额外信息**
|
|
其他相关信息
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 文档贡献
|
|
|
|
### 文档类型
|
|
|
|
- README 和快速开始
|
|
- API 使用指南
|
|
- 部署文档
|
|
- 故障排查
|
|
- 架构说明
|
|
|
|
### 文档规范
|
|
|
|
- 使用 Markdown 格式
|
|
- 代码示例使用代码块
|
|
- 添加适当的标题层级
|
|
- 包含实际可运行的示例
|
|
|
|
---
|
|
|
|
## 🎯 优先级
|
|
|
|
### 高优先级
|
|
- Bug 修复
|
|
- 安全漏洞修复
|
|
- 性能优化
|
|
- 核心功能增强
|
|
|
|
### 中优先级
|
|
- 新功能
|
|
- 代码重构
|
|
- 测试增强
|
|
- 文档改进
|
|
|
|
### 低优先级
|
|
- 代码风格调整
|
|
- 次要功能
|
|
- 实验性功能
|
|
|
|
---
|
|
|
|
## 📞 联系方式
|
|
|
|
- **GitHub Issues**: 报告 bug 和功能请求
|
|
- **Pull Requests**: 贡献代码
|
|
- **Email**: support@xiaoxia-saas.com
|
|
|
|
---
|
|
|
|
## 📄 许可证
|
|
|
|
贡献的代码将使用与项目相同的许可证。
|
|
|
|
---
|
|
|
|
感谢你的贡献！🎉
|