4.4 KiB
4.4 KiB
贡献指南
感谢你对小虾 SaaS 项目的兴趣！
🚀 快速开始
1. Fork 和克隆
# Fork 项目到你的账号
# 然后克隆
git clone https://github.com/your-username/xiaoxia-saas.git
cd xiaoxia-saas
2. 设置开发环境
# 创建虚拟环境
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. 运行测试
# 运行所有测试
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
- 每个文件顶部添加模块说明
代码格式化
# 安装工具
pip install black isort
# 格式化代码
black packages/ apps/ tests/
isort packages/ apps/ tests/
架构原则
- 遵循 Clean Architecture
- 业务逻辑在 Application 层
- 基础设施在 Adapters 层
- 保持层次间依赖方向正确
🧪 测试要求
单元测试
- 所有新功能必须有单元测试
- 测试覆盖率不低于 80%
- 使用 pytest fixtures
- Mock 外部依赖
测试示例
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. 创建分支
# 从 main 创建功能分支
git checkout -b feat/your-feature-name
2. 开发和测试
# 编写代码
# 运行测试
pytest tests/ -v
# 提交
git add .
git commit -m "feat: your feature description"
3. 推送和创建 PR
# 推送到你的 fork
git push origin feat/your-feature-name
# 在 GitHub 上创建 Pull Request
4. PR 描述模板
## 变更说明
简要描述此 PR 的目的
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他
## 测试
- [ ] 添加了单元测试
- [ ] 所有测试通过
- [ ] 手动测试通过
## 截图（如适用）
添加相关截图
## 相关 Issue
Closes #issue_number
🐛 报告 Bug
Bug 报告模板
**描述**
清晰描述 bug
**复现步骤**
1. 进入 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 看到错误
**期望行为**
描述期望发生什么
**实际行为**
描述实际发生了什么
**环境**
- OS: [e.g. Ubuntu 22.04]
- Python: [e.g. 3.12]
- 浏览器: [e.g. Chrome 120]
**额外信息**
添加任何其他相关信息
💡 功能建议
功能请求模板
**功能描述**
简要描述建议的功能
**问题**
此功能解决什么问题？
**建议方案**
描述你期望的解决方案
**替代方案**
考虑过哪些替代方案？
**额外信息**
其他相关信息
📚 文档贡献
文档类型
- README 和快速开始
- API 使用指南
- 部署文档
- 故障排查
- 架构说明
文档规范
- 使用 Markdown 格式
- 代码示例使用代码块
- 添加适当的标题层级
- 包含实际可运行的示例
🎯 优先级
高优先级
- Bug 修复
- 安全漏洞修复
- 性能优化
- 核心功能增强
中优先级
- 新功能
- 代码重构
- 测试增强
- 文档改进
低优先级
- 代码风格调整
- 次要功能
- 实验性功能
📞 联系方式
- GitHub Issues: 报告 bug 和功能请求
- Pull Requests: 贡献代码
- Email: support@xiaoxia-saas.com
📄 许可证
贡献的代码将使用与项目相同的许可证。
感谢你的贡献！🎉