贡献指南

感谢您对 billx 项目的兴趣！我们欢迎所有形式的贡献。

🤝 如何贡献

报告问题

如果您发现了 bug 或有功能建议：

1. 检查 Issues 页面 确认问题是否已被报告
2. 如果是新问题，创建一个 Issue 并提供详细信息：
   • 清晰的标题
   • 详细的问题描述
   • 重现步骤
   • 预期行为
   • 实际行为
   • 环境信息（操作系统、版本号等）
   • 相关的错误日志

功能建议

对于新功能的建议：

1. 在 Issues 中使用 Feature Request 模板
2. 详细描述功能需求和用例
3. 解释为什么这个功能有价值
4. 提供可能的实现思路（如果了解）

代码贡献

开发环境设置

# 克隆仓库
git clone https://github.com/tyrad/billx.git
cd billx

# 安装 Go 依赖
make deps

# 安装 Node.js 依赖
cd web && npm install
cd ..

# 验证环境
make test

分支管理

• main - 主分支，保持稳定状态
• develop - 开发分支，最新的开发代码
• feature/* - 功能分支
• hotfix/* - 紧急修复分支

开发流程

1. 创建分支：

   # 功能开发
   git checkout -b feature/your-feature-name develop
   
   # Bug 修复
   git checkout -b fix/your-fix-name main

2. 开发：

   • 遵循项目的代码风格
   • 添加适当的测试
   • 确保所有测试通过
   • 更新相关文档

3. 提交代码：

   # 添加文件到暂存区
   git add .
   
   # 提交代码
   git commit -m "feat: add new feature description"

4. 推送分支：

   git push origin feature/your-feature-name

5. 创建 Pull Request：

   • 在 GitHub 上创建 PR
   • 选择合适的目标分支
   • 填写 PR 描述
   • 等待代码审查

提交信息规范

使用 Conventional Commits 格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型说明：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式化（不影响功能）
• refactor: 代码重构（不影响功能）
• test: 测试相关
• chore: 构建过程或辅助工具的变动

示例：

git commit -m "feat: add OpenAI API integration for bill categorization"
git commit -m "fix: resolve database connection timeout issue"
git commit -m "docs: update README with installation instructions"
git commit -m "test: add unit tests for bill service"

代码审查

所有 Pull Request 都需要经过代码审查：

• 自动检查：CI/CD 流水线会自动运行测试和检查
• 人工审查：至少一位维护者审查代码
• 审查要点：
  • 代码质量和可读性
  • 测试覆盖率
  • 文档更新
  • 性能影响
  • 安全考虑

测试

运行测试

# 运行所有测试
make test

# 运行单元测试
make test-unit

# 运行集成测试
make test-integration

# 运行基准测试
make test-bench

# 查看测试覆盖率
make coverage

测试要求

• 新功能必须包含相应的测试
• 修复 bug 时需要添加回归测试
• 保持测试覆盖率在可接受水平
• 确保测试在所有支持的平台上通过

📝 文档贡献

文档是项目的重要组成部分，我们欢迎文档贡献：

改进现有文档

• 修复错别字和语法错误
• 改进代码注释
• 更新过时的信息
• 添加示例和截图

添加新文档

• API 使用指南
• 部署指南
• 故障排除指南
• 最佳实践指南

文档格式

• 使用 Markdown 格式
• 遵循现有的文档结构
• 保持简洁明了
• 包含适当的代码示例

🌍 国际化

项目支持多语言：

• 添加新语言支持
• 改进翻译质量
• 修复语言相关 bug

🎨 设计贡献

如果您是设计师，可以通过以下方式贡献：

• UI/UX 改进建议
• 设计稿和原型
• 图标和图片资源
• 响应式设计优化

🐛 调试和问题解决

调试技巧

1. 本地调试：

   # 启动开发模式
   make run
   
   # 启动完整模式
   make run-full

2. 日志分析：

   • 查看应用日志
   • 使用调试工具
   • 检查网络请求

3. 性能分析：

   # 运行性能测试
   make test-bench

常见问题

• 构建失败：检查依赖版本和环境配置
• 测试失败：确保数据库和网络连接正常
• 部署问题：检查服务器配置和权限

🏆 贡献者荣誉

所有贡献者都会在 贡献者列表 中获得认可：

• 代码贡献者
• 文档贡献者
• 设计贡献者
• 社区支持者

📞 联系方式

如果您有任何问题或需要帮助：

• 技术讨论：GitHub Discussions
• 问题反馈：GitHub Issues
• 邮件联系：通过 GitHub Issues 私信

📜 行为准则

请阅读并遵守我们的 行为准则：

• 尊重所有贡献者
• 保持专业和友善的态度
• 欢迎不同观点的建设性讨论
• 零容忍歧视和骚扰

🔒 安全相关

如果您发现安全漏洞：

• 请不要在 Issues 中公开讨论
• 私密报告给维护者
• 提供详细的影响范围和复现步骤
• 配合修复和发布流程

📊 项目统计

• 代码贡献统计：GitHub Insights
• 问题解决统计：Issues Dashboard
• 活跃度分析：Pulse

---

感谢您的贡献！ 🎉

您的每一份贡献都会让项目变得更好。无论是代码、文档、测试还是社区支持，我们都非常感谢。