TheRock开源贡献指南：从提交PR到成为核心开发者

【免费下载链接】TheRockThe HIP Environment and ROCm Kit - A lightweight open source build system for HIP and ROCm项目地址: https://gitcode.com/gh_mirrors/th/TheRock

TheRock作为轻量级开源构建系统，为HIP和ROCm提供强大支持。本指南将带你从提交第一个PR开始，逐步掌握贡献流程，最终成长为核心开发者，助力开源社区发展。

一、贡献前准备：快速融入社区

1.1 了解项目架构与规范

TheRock项目结构清晰，核心代码位于多个目录中。开发前建议阅读docs/development/build_system.md了解构建系统架构，以及docs/development/style_guides/中的编码规范，包括Bash、CMake、GitHub Actions和Python风格指南，确保代码符合项目标准。

1.2 搭建开发环境

• 克隆仓库：使用命令git clone https://gitcode.com/gh_mirrors/th/TheRock获取源码
• 安装依赖：根据docs/environment_setup_guide.md配置环境，关键步骤包括安装patchelf：

  sudo env INSTALL_PREFIX=/usr/local ./dockerfiles/install_pinned_patchelf.sh

• 配置开发工具：推荐使用VSCode，参考docs/development/assets/vscode_cmake_tools_project_outline.jpg配置CMake工具，提升开发效率。

二、提交PR：从零开始的贡献流程

2.1 寻找合适的任务

• 新手可从good first issue入手，这些任务范围小、难度低
• 进阶贡献者可选择help wanted标签的任务，解决实际问题

2.2 创建分支与提交代码

• 分支命名：遵循规范，个人开发分支格式为users/[USERNAME]/[feature-or-bug-name]，例如users/cooldev/fix-cmake-warning
• 提交规范：使用清晰的提交信息，参考Conventional Commits格式
• 预检查：运行pre-commit工具确保代码质量：

  pip install pre-commit pre-commit run --all-files

2.3 编写PR描述

PR描述需包含以下关键信息：

• 关联issue（如Fixes #123）
• 功能或修复说明
• 测试方法
• 影响范围

参考skills/therock_pr_bot/FAQ.md#-pr-description了解详细要求，PR模板位于.github/pull_request_template.md。

2.4 提交PR与触发CI

提交PR后，系统会自动运行CI检查。可通过GitHub Actions界面查看构建状态，如图所示：

若CI失败，根据日志修复问题。关键检查包括：

• 代码风格（pre-commit）
• 单元测试（unit_tests.yml）
• 构建验证

三、PR审核：提升贡献质量的关键步骤

3.1 理解审核标准

审核关注以下方面：

• 代码质量：是否符合编码规范
• 测试覆盖：是否添加单元测试（参考docs/development/adding_tests.md）
• 性能影响：构建时间、内存使用等
• 兼容性：是否影响其他模块

3.2 响应审核意见

• 及时回复评论，清晰解释设计思路
• 根据反馈修改代码后，使用"Re-request review"功能通知审核者：

• 大型修改建议分多次提交，保持PR聚焦

3.3 处理CI反馈

CI失败常见原因及解决方法：

• 编译错误：检查依赖配置，参考cmake/therock_subproject.cmake
• 测试失败：查看详细日志，使用test_tools/determine_rocm_test_dependencies.py分析依赖
• 格式问题：运行pre-commit run自动修复

四、成为核心开发者：持续贡献与社区参与

4.1 深化技术理解

• 学习项目核心模块：
  • 构建系统：cmake/therock_subproject.cmake
  • 依赖管理：build_tools/_therock_utils/artifacts.py
  • CI流程：build_tools/github_actions/configure_multi_arch_ci.py
• 参与架构讨论：关注RFCs文档，如RFC0012-Repo-Structure.md

4.2 扩大贡献范围

• 维护子模块：如math-libs/BLAS/中的rocBLAS集成
• 改进工具链：优化build_tools/setup_ccache.py等构建工具
• 编写文档：完善docs/development/中的指南，帮助新贡献者

4.3 社区参与

• 在Discord的#therock-contributors频道交流
• 参与代码审查，帮助其他贡献者提升PR质量
• 定期参加社区会议，分享贡献经验

五、高级技巧：提升贡献效率

5.1 利用AI工具辅助开发

项目支持使用AI工具提升效率，参考CLAUDE.md和skills/rocm-pr-quality/中的AI辅助指南。使用时需确保：

• 人工验证AI生成内容
• 遵守项目AI使用政策

5.2 优化构建流程

• 使用ccache加速编译：docs/development/ccache_troubleshooting.md
• 本地复现CI环境：参考docs/development/test_environment_reproduction.md

5.3 跟踪贡献影响

提交PR后，可通过CI步骤摘要查看构建结果和测试覆盖率：

关注S3 buckets中的构建产物，了解贡献对下游项目的影响。

六、常见问题与解决方案

6.1 PR被标记为"Not ready to Review"

通常由于：

• 描述不完整：补充issue链接和详细说明
• 测试缺失：添加单元测试或解释豁免原因
• 风格问题：运行pre-commit run --all-files修复

6.2 构建依赖冲突

• 检查BUILD_TOPOLOGY.toml中的子项目依赖
• 使用./build_tools/fetch_artifacts.py获取正确版本的预构建组件

6.3 权限问题

外部贡献者PR可能遇到权限限制，可：

• 通过workflow_dispatch触发特殊CI
• 在issue中请求核心开发者协助测试

结语

TheRock社区欢迎所有开发者贡献力量，从修复小bug到参与架构设计，每一份贡献都至关重要。遵循本指南，你将快速融入社区，逐步成长为核心开发者，共同推动HIP和ROCm生态的发展。开始你的贡献之旅吧！

【免费下载链接】TheRockThe HIP Environment and ROCm Kit - A lightweight open source build system for HIP and ROCm项目地址: https://gitcode.com/gh_mirrors/th/TheRock