TheRock/rocm-libraries/projects/rocthrust/CONTRIBUTING.md

<head> </head>

Contributing to rocThrust

We welcome contributions to rocThrust. Please follow these details to help ensure your contributions will be successfully accepted.

Issue Discussion

Please use the GitHub Issues tab to notify us of issues.

• Use your best judgement for issue creation. If your issue is already listed, upvote the issue and comment or post to provide additional details, such as how you reproduced this issue.
• If you're not sure if your issue is the same, err on the side of caution and file your issue. You can add a comment to include the issue number (and link) for the similar issue. If we evaluate your issue as being the same as the existing issue, we'll close the duplicate.
• If your issue doesn't exist, use the issue template to file a new issue.
  • When filing an issue, be sure to provide as much information as possible, including script output so we can collect information about your configuration. This helps reduce the time required to reproduce your issue.
  • Check your issue regularly, as we may require additional information to successfully reproduce the issue.
• You may also open an issue to ask questions to the maintainers about whether a proposed change meets the acceptance criteria, or to discuss an idea pertaining to the library.

Acceptance Criteria

rocThrust is a version of the Thrust parallel algorithms library that has been ported to HIP and ROCm. This allows the library to be used on AMD GPU devices.

Code in rocThrust should perform only the work that's necessary to support the Thrust API - any algorithmic work should be passed off to the backend system. On AMD platforms, this backend is rocPRIM.

In order to prevent performance regressions, when a pull request is created, a number of automated checks are run. These checks:

• test the change on various OS platforms (Ubuntu, RHEL, etc.)
• run on different GPU architectures (MI-series, Radeon series cards, etc.)
• run benchmarks to check for performance degredation

In order for change to be accepted:

• it must pass all of the automated checks
• it must undergo a code review

The GitHub "Issues" tab may also used to discuss ideas surrounding particular features or changes before raising pull requests.

Code Structure

Thrust library code is located in the /thrust/ directory. The majority of the code required for porting the library to hip is located in /thrust/system/hip/. HIP tests are located in the /test/ directory, while the original Thrust cuda tests can be found in /testing/.

Coding Style

C and C++ code should be formatted using clang-format. Use the clang-format version for Clang 9, which is available in the /opt/rocm directory. Please do not use your system's built-in clang-format, as this is an older version that will have different results.

To format a file, use:

/opt/rocm/hcc/bin/clang-format -style=file -i <path-to-source-file>

To format all files, run the following script in rocThrust directory:

#!/bin/bash
git ls-files -z *.cc *.cpp *.h *.hpp *.cl *.h.in *.hpp.in *.cpp.in | xargs -0 /opt/rocm/hcc/bin/clang-format  -style=file -i

Also, githooks can be installed to format the code per-commit:

./.githooks/install

Pull Request Guidelines

Our code contribution guidelines closely follows the model of GitHub pull-requests.

When you create a pull request, you should target the default branch. Our current default branch is the develop branch, which serves as our integration branch. Releases are cut to release/rocm-rel-x.y, where x and y refer to the release major and minor numbers.

Deliverables

New changes should include test coverage. HIP tests are located in the /test/ directory, while the original Thrust cuda tests can be found in /testing/.

Process

After you create a PR, you can take a look at a diff of the changes you made using the PR's "Files" tab.

PRs must pass through the checks and the code review described in the Acceptance Criteria section before they can be merged.

Checks may take some time to complete. You can view their progress in the table near the bottom of the pull request page. You may also be able to use the links in the table to view logs associated with a check if it fails.

During code reviews, another developer will take a look through your proposed change. If any modifications are requested (or further discussion about anything is needed), they may leave a comment. You can follow up and respond to the comment, and/or create comments of your own if you have questions or ideas. When a modification request has been completed, the conversation thread about it will be marked as resolved.

To update the code in your PR (eg. in response to a code review discussion), you can simply push another commit to the branch used in your pull request.