Contributor’s Guide

4. Contributor’s Guide#

4.1. 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.

4.2. Pull-request guidelines#

Our code contriubtion guidelines closely follows the model of GitHub pull-requests. The rocWMMA repository follows a workflow which dictates a /master branch where releases are cut, and a /develop branch which serves as an integration branch for new code. Pull requests should:

  • target the develop branch for integration

  • ensure code builds successfully.

  • do not break existing test cases

  • new functionality will only be merged with new unit tests

  • new unit tests should integrate within the existing googletest framework.

  • tests must have good code coverage

  • code must also have benchmark tests, and performance must approach the compute bound limit or memory bound limit.

4.3. StyleGuide#

This project follows the CPP Core guidelines, with few modifications or additions noted below. All pull-requests should in good faith attempt to follow the guidelines stated therein, but we recognize that the content is lengthy. Below we list our primary concerns when reviewing pull-requests.

4.3.1. Interface#

  • Library code should use C++17

  • Our minimum supported compiler is hipcc 4.4

  • Avoid CamelCase

  • This rule applies specifically to publicly visible APIs, but is also encouraged (not mandated) for internal code

4.3.2. Philosophy#

  • P.2: Write in ISO Standard C++14 (especially to support windows, linux and macos plaforms )

  • P.5: Prefer compile-time checking to run-time checking

4.3.3. Implementation#

  • SF.1: Use a .cpp suffix for code files and an .hpp suffix for interface files if your project doesn’t already follow another convention

  • SF.5: A .cpp file must include the .hpp file(s) that defines its interface

  • SF.7: Don’t put a global using-directive in a header file

  • SF.8: Use #include guards for all .hpp files

  • SF.21: Don’t use an unnamed (anonymous) namespace in a header

  • SL.10: Prefer using std::array or std::vector instead of a C array

  • C.9: Minimize the exposure of class members

  • F.3: Keep functions short and simple

  • F.21: To return multiple ‘out’ values, prefer returning a std::tuple

  • R.1: Manage resources automatically using RAII (this includes std::unique_ptr & std::shared_ptr)

  • ES.11: Use auto to avoid redundant repetition of type names

  • ES.20: Always initialize an object

  • ES.23: Prefer the {} initializer syntax

  • CP.1: Assume that your code will run as part of a multi-threaded program

  • I.2: Avoid global variables

4.3.4. Format#

C++ code is formatted using clang-format. To run clang-format use the version in the /opt/rocm/llvm/bin directory. Please do not use your system’s built-in clang-format, as this may be an older version that will result in different 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 rocWMMA 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

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

./.githooks/install
Contents