Contributing to hipTensor

This document provides the coding guidelines for contributing to the hipTensor APIs.

License agreement

1. The code I am contributing is mine and I have the right to license it.

2. By submitting a pull request for this project, I am granting you a license to distribute said code under the MIT License for the project.

Pull-request guidelines

Our code contribution guidelines closely follows the model of GitHub pull-requests. The hipTensor repository uses a workflow with a release branch for releases and a develop branch for integrating new code. Follow the guidelines below when creating a pull request:

• Target the develop branch for integration.

• Ensure that the code builds successfully.

• Do not break existing test cases.

• Be informed that a new functionality is only merged with new unit tests.

• Ensure that new unit tests integrate within the existing GoogleTest framework.

• Design the tests with thorough code coverage.

• Include benchmark tests and ensure performance approaches the compute-bound or memory-bound limits.

Style guide

This project follows the CPP Core guidelines, with a few modifications and additions listed below. Follow these guidelines when creating pull requests.

Interface

• Use C++17 for the library code.

• Avoid camel case.

Note

The above rules specifically apply to publicly visible APIs, but are also encouraged, though not required, for internal code.

Philosophy

• Use ISO Standard C++14 to ensure compatibility across Windows, Linux, and macOS platforms.

• Prefer compile-time check to run-time check.

Implementation

• Use the .cpp suffix for code files and .hpp suffix for interface files, if your project doesn’t already follow another convention.

• Ensure that each .cpp file includes the .hpp file(s) that defines its interface.

• Avoid placing global using directives in header files.

• Use #include guards for all .hpp files.

• Avoid using unnamed (anonymous) ``namespace``s in header files.

• Use std::array or std::vector instead of C arrays.

• Minimize the exposure of class members.

• Keep functions short and simple.

• To return multiple output values, prefer using a std::tuple.

• Manage resources automatically using RAII, including std::unique_ptr and std::shared_ptr.

• Use auto to avoid redundant repetition of type names.

• Always initialize an object.

• Use the {} initializer syntax wherever possible.

• Expect your code to run as part of a multi-threaded program.

• Avoid using global variables.

Format

C++ code is formatted using clang-format. To run clang-format, use the version in the /opt/rocm/llvm/bin directory. Avoid using your system’s built-in clang-format, as it might be outdated and produce inconsistent results.

To format a file, use:

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

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

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

To install githooks to format the code per-commit, use:

./.githooks/install

Example

1. Create and track a hipTensor fork.

2. Clone your fork:

   git clone -b develop https://github.com/<your_fork>/hipTensor.git .
   .githooks/install
   git checkout -b <new_branch>
   ...
   git add <new_work>
   git commit -m "What was changed"
   git push origin <new_branch>
   ...
   

3. Create a pull request to ROCm/hipTensor, targeting the develop branch.

4. Respond to code reviews.

5. Await CI and approval feedback.

6. Once approved, await for dev team to merge!

Note

Install the githooks via .githooks/install, as there are triggers for clang formatting in commits.