torch-rechub

中文

English

中文

English

Appearance

贡献指南 ​

感谢您对 Torch-RecHub 的兴趣！我们欢迎各种形式的贡献，包括但不限于：

  • 🐛 Bug 报告
  • 💡 功能建议
  • 📝 文档改进
  • 🔧 代码贡献
  • 🧪 测试用例
  • 📖 教程和示例

🚀 快速开始 ​

开发环境设置 ​

bash
# 1. Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/torch-rechub.git
cd torch-rechub

# 2. 安装依赖并设置环境
uv sync

# 3. 以开发模式安装包
uv pip install -e .

开发工作流 ​

  1. Fork 仓库：点击右上角的 "Fork" 按钮。
  2. 进行修改：实现新功能或修复 Bug。
  3. 格式化代码：在提交前运行代码格式化以确保代码风格一致：
    bash
    python config/format_code.py
  4. 提交更改：git commit -m "feat: add new feature" 或 git commit -m "fix: fix some issue"（推荐遵循 Conventional Commits）。
  5. 推送到分支：git push origin
  6. 创建 Pull Request：返回原始仓库页面，点击 "New pull request"，将您的分支与主仓库的 main 分支进行比较，然后提交 PR。

📋 代码规范 ​

分支命名 ​

  • feature/feature-name - 新功能
  • fix/bug-description - Bug 修复
  • docs/documentation-update - 文档更新
  • test/test-description - 测试添加

提交信息 ​

我们遵循 Conventional Commits 规范：

  • feat: 添加新的推荐模型
  • fix: 解决训练循环中的内存泄漏
  • docs: 更新安装指南
  • test: 为 DeepFM 模型添加单元测试
  • refactor: 优化数据加载管道

Pull Request 流程 ​

  1. 推送您的分支

    bash
    git push origin your-branch-name

  2. 创建 Pull Request

    • 访问 GitHub 仓库页面
    • 点击 "New pull request"
    • 选择您的分支
    • 填写 PR 模板

  3. PR 要求

    • 清晰的更改描述
    • 解释为什么需要这些更改
    • 列出相关的 Issue（如果有）
    • 包含测试说明
    • 添加截图（如适用）

🧪 测试指南 ​

编写测试 ​

  • 单元测试：测试单个函数或类
  • 集成测试：测试模块之间的交互
  • 端到端测试：测试完整的工作流

运行测试 ​

bash
# 运行所有测试
uv run pytest

# 运行特定测试文件
uv run pytest tests/test_models/test_ranking.py

# 运行并生成覆盖率报告
uv run pytest --cov=torch_rechub

📝 文档 ​

文档类型 ​

  • API 文档：代码中的文档字符串
  • 用户指南：docs/ 目录中的文件
  • 教程：tutorials/ 目录中的 Jupyter 笔记本
  • README：项目介绍和快速开始

文档规范 ​

  • 使用 Markdown 格式
  • 包含代码示例
  • 提供清晰的分步说明
  • 保持英文和中文版本同步
  • 遵循 Google 风格的 Python 文档字符串

🎯 贡献想法 ​

适合初学者的任务 ​

  • 📖 改进文档和注释
  • 🧪 添加测试用例
  • 🐛 修复简单的 Bug
  • 📝 翻译文档
  • 💡 添加示例代码
  • 🔧 代码格式化和风格改进

高级贡献 ​

  • 🚀 实现新的推荐算法
  • ⚡ 性能优化
  • 🏗️ 架构改进
  • 📊 添加新的评估指标
  • 🛠️ 开发工具和脚本
  • 🔬 研究论文实现

模型实现指南 ​

实现新模型时：

  1. 遵循现有模式：查看现有模型的结构
  2. 添加全面的测试：包括单元测试和集成测试
  3. 提供示例：在 examples/ 目录中添加使用示例
  4. 详细文档：包括文档字符串和 README 更新
  5. 性能基准：与现有实现进行比较

📞 获取帮助 ​

如果您在贡献过程中遇到问题：

  1. 查看现有 Issues：可能有相关讨论
  2. 创建新 Issue：清楚地描述您的问题
  3. 加入讨论：在相关 Issues 或 PR 中提问
  4. 联系维护者：通过 GitHub 或电子邮件

🏆 认可 ​

我们重视每一项贡献！所有贡献者将在以下位置获得认可：

  • README 中的贡献者列表
  • 发布说明中的致谢
  • 项目文档中的贡献者页面
  • 重大贡献的特别提及

📜 行为准则 ​

请遵守我们的 行为准则 以确保友好和包容的社区环境。

再次感谢您的贡献！每一项贡献都让 Torch-RecHub 变得更好。🎉