Contributing to TheRock

We are enthusiastic about contributions to our code and documentation. Please feel free to file issues where documentation or functionality is lacking or, even better, volunteer to contribute to help close these gaps!

Developer policies

These policies apply to all forms of activity and engagement in this project.

Project governance

See ROCm Project Governance, which also defines the code of conduct.

Licensing

Code contributions to this project are covered under the terms of the LICENSE file.

Communication channels

TheRock uses GitHub as the source of truth for all issue tracking, project planning, and code contributions. This makes it easy for developers across companies to observe the project and contribute. We also leverage an open source stack for our development tools and infrastructure so that forks and downstream projects can benefit too.

We are also active on the AMD Developer Community Discord Server in channels like #therock-contributors and #rocm-build-install-help.

AI tool use policy

We allow the use of AI tools to help author issues, pull requests, reviews, comments, and more.

While we don't have a formal AI tool use policy in the ROCm GitHub organization at the moment, we are actively monitoring contribution patterns and take inspiration from policies in neighboring ecosystem projects:

• https://llvm.org/docs/AIToolPolicy.html
• https://github.com/pytorch/pytorch/blob/main/AI_POLICY.md

Of particular note, from the LLVM AI Tool Use Policy:

The contributor is always the author and is fully accountable for their contributions. Contributors should be sufficiently confident that the contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work during review.

When posting significant portions of AI-generated content on issues or pull requests, we also encourage contributors to clearly disclose which sections of a comment are human or AI-generated (e.g. using a code or quote block, or by posting the output to https://gist.github.com/) along with accompanying human commentary explaining the relevance and accuracy of the content.

Branch creation policy

Most contributions from AMD employees should be made via branches in the shared repository and not personal forks according to the http://u.amd.com/rocm-oss-contributing policy. Branches in the shared repository benefit from code security scanning, code quality tooling, and easier collaboration.

For external contributors, PRs from forks are of course accepted and most workflows are compatible with this contribution model.

Branch naming policy

Branches in personal forks can use any name.

Branches created in the shared repository should match one of these patterns so branches are easily sortable and can be audited by repository maintainers:

Branch name pattern	Example
users/[USERNAME]/[feature-or-bug-name]	users/cooldeveloper/my-feature
shared/[feature-or-bug-name]	shared/kpack-integration

A few exceptions are granted for automation and some subproject-specific branch naming conventions:

• bump-*
• revert-*
• dependabot/**/*
• copilot/**/*
• compiler-*
• amd-compiler-*
• amd/dev/**/*
• amd/staging/**/*

Additionally, a few long-lived branches exist using other patterns:

• main
• release/*
• compiler/amd-staging

Branch naming is enforced via a branch protection ruleset that restricts branch creation (specifically this ruleset for maintainers).

Development workflows and contributing guide

Finding an issue to work on

If you want to contribute but don't have a specific problem in mind, the issue tracker is the best place to start. These two labels mark work we hope someone outside the core team will pick up:

Label	What it means
help wanted	Understood well enough for someone outside the core team to pick up, and no maintainer is working on it. Start here.
good first issue	Small in scope and unlikely to need wide-ranging changes across the build. Usually also carries help wanted.

Triaged issues carry other labels you can combine with those two to find something in an area you already know:

• status: * shows how far along an issue is. status: assessed means the root cause is already known.
• project: *, gfx*, platform: *, and ecosystem: * identify the affected component, GPU family, host platform, and downstream project.
• build issue, CICD, documentation, and test-debt are good places to look for contributions that don't need specific GPU hardware.

If an issue is missing information you need, or you think it deserves one of the labels above, say so in the thread and a maintainer will take another look.

Do I need to ask before working on an issue?

No, but please comment on the issue to say you are picking it up so others don't duplicate your effort. We don't lock issues to one person, and an existing assignee doesn't stop you from opening a pull request. If multiple pull requests address the same issue, we take the highest quality one (or the first one, if they are comparable).

When your change is ready, follow Creating pull requests.

Using GitHub Issues for bug reporting

Before filing a new issue, please search through existing issues to make sure your issue hasn't already been reported.

General issue guidelines:

• Use your best judgement for new issue creation. If you find a similar open (or closed) issue already reported, upvote the issue and leave a comment with any new details, such as how you reproduced it.
• When filing an issue, be sure to provide as much information as possible, including reproduction steps and complete script output so we can triage efficiently.
• Check your issue regularly, as we may require additional information to resolve the issue.

Using GitHub Issues for feature development

Discussion about new features is welcome via

• Filing a GitHub issue
• Posting a GitHub discussion
• Reaching out on Discord

Creating pull requests

To keep code quality high across the project, we hold pull requests to the following standards:

Check description	Enforced via	Details
✅ Code style guidelines	Manual code review	Coding style guides
✅ Branch naming patterns	Repository ruleset	Branch naming policy (users/USERNAME/feature-name)
✅ Pull requests should link an issue	therock-pr-bot.yml	pull_request_template.md Policy Bot FAQ.md
✅ Lint pre-commit checks	pre-commit.yml	pre-commit checks
✅ Changes should be unit tested	unit_tests.yml therock-pr-bot.yml	(Planned) TESTING.md file docs/development/adding_tests.md

Coding style guides

We have project-wide style guides with recommendations to follow at docs/development/style_guides/:

• Bash Style Guide
• CMake Style Guide
• GitHub Actions Style Guide
• Python Style Guide

Improvements to the style guides are welcome, particularly for common patterns observed across multiple commits.

Linking pull requests to GitHub issues

All pull requests should be associated with at least one GitHub issue.

This lets reviewers see the context for contributions, helps link bugs and their fixes together, and helps with release planning. See also the Using GitHub Issues for bug reporting and Using GitHub Issues for feature development sections above.

• The repository pull_request_template.md has a section for this.
• Our PR Policy Bot enforces this by checking for references in the pull request description such as:

  Fixes https://github.com/ROCm/TheRock/issues/123
  

  See the "PR Description" section of therock_pr_bot/FAQ.md for full details.
• Contributions by AMD employees may also/instead reference a JIRA ID, though GitHub issues are preferred for open source development.
• Exceptions may be granted on a case-by-case basis via the PR Policy Bot.

pre-commit checks

We use pre-commit to run automated "hooks" like lint checks and formatters on each commit. See the list of hooks we currently run at .pre-commit-config.yaml. Contributors are encouraged to download pre-commit and run it on their commits before sending pull requests for review.

For example:

# Download (note: this is already included in requirements.txt).
pip install pre-commit

# Run locally on staged files.
pre-commit run

# Run locally on all files.
pre-commit run --all-files

# Install the git hook.
pre-commit install

Requesting a code review

If you are not looking for a review on a pull request yet, please mark that pull request as a draft:

• 
• GitHub Docs: Creating a pull request
• GitHub Docs: Changing the stage of a pull request

When you are ready for a review, please request a review from a maintainer and mark the PR as not a draft as needed:

• 
• 
• GitHub Docs: Requesting a pull request review

You can check the git history to see who recently authored or approved PRs in the same files or folders:

• CODEOWNERS
  • GitHub Docs: About code owners
  • .github/CODEOWNERS
• Checking history
  • GitHub Docs: Viewing and understanding files
  • GitHub Docs: Differences between commit views