贡献指南

感谢您对 HeurAMS 项目的关注！我们欢迎所有形式的贡献，包括代码、文档、测试、功能建议等。

🎯 贡献类型

代码贡献

• Bug 修复 - 修复已知问题
• 功能开发 - 实现新功能
• 性能优化 - 提升系统性能
• 代码重构 - 改进代码质量

文档贡献

• 文档编写 - 补充技术文档
• 示例代码 - 提供使用示例
• 翻译工作 - 多语言文档

测试贡献

• 单元测试 - 编写测试用例
• 集成测试 - 测试模块集成
• 性能测试 - 性能基准测试

🚀 开始贡献

开发环境搭建

1. Fork 项目

   # Fork 项目到您的 GitHub 账户
   # 然后克隆到本地
   git clone https://github.com/your-username/heurams.git
   cd heurams

2. 设置开发环境

   # 创建虚拟环境
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   # 或 venv\Scripts\activate  # Windows
   
   # 安装依赖
   pip install -r requirements.txt
   pip install -r requirements-dev.txt

3. 运行测试

   # 运行所有测试
   pytest
   
   # 运行特定测试
   pytest tests/test_kernel.py

代码规范

Python 代码规范

• 遵循 PEP 8 规范
• 使用 Black 进行代码格式化
• 使用 isort 进行导入排序
• 使用 flake8 进行代码检查

# 代码格式化
black .
isort .
flake8 .

提交信息规范

• 使用英文编写提交信息
• 遵循 Conventional Commits 规范
• 提交信息格式：type(scope): description

示例：

feat(kernel): add SM-2 algorithm implementation
fix(interface): resolve memory leak in UI components
docs(api): update kernel API documentation

提交 Pull Request

1. 创建功能分支

   git checkout -b feature/your-feature-name

2. 开发并测试

   • 编写代码
   • 添加测试用例
   • 确保所有测试通过

3. 提交代码

   git add .
   git commit -m "feat(module): your feature description"
   git push origin feature/your-feature-name

4. 创建 Pull Request

   • 在 GitHub 上创建 PR
   • 填写详细的描述
   • 关联相关 Issue

📋 代码审查流程

审查标准

• 功能完整性 - 功能按预期工作
• 代码质量 - 遵循代码规范
• 测试覆盖 - 有充分的测试用例
• 文档更新 - 相关文档已更新

审查流程

1. 自动化检查 - CI/CD 流水线运行
2. 代码审查 - 核心维护者审查
3. 测试验证 - 功能测试验证
4. 合并发布 - 通过后合并到主分支

🐛 报告问题

Bug 报告

当报告 Bug 时，请提供：

• 问题描述 - 详细的问题描述
• 重现步骤 - 如何重现问题
• 环境信息 - 操作系统、Python 版本等
• 日志信息 - 相关的错误日志

功能请求

当提出功能请求时，请提供：

• 功能描述 - 详细的功能描述
• 使用场景 - 功能的使用场景
• 实现建议 - 可能的实现方式

🏆 贡献者权益

贡献者名单

所有贡献者将被列入项目贡献者名单。

代码署名

您的贡献将在 Git 提交历史中永久记录。

社区认可

重要的贡献将被特别认可和感谢。

❓ 常见问题

Q: 如何开始第一个贡献？

A: 建议从修复简单的 Bug 或改进文档开始。

Q: 需要签署 CLA 吗？

A: 目前不需要签署贡献者许可协议。

Q: 如何获取开发帮助？

A: 可以通过 GitHub Issues 或社区讨论获取帮助。

---

感谢您的贡献！您的每一份努力都让 HeurAMS 变得更好。