diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..7ba0f5f82 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,139 @@ +
+ + + + + +# Contributing to rocPRIM # + +We welcome contributions to rocPRIM. 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 ## + +rocPRIM provides a number of foundational parallel algorithms that have optimized for AMD ROCm platforms. +The purpose of the library is provide a reliable, performant foundation upon which other libraries can build. +Algorithms are written in HIP to maximize portability. + +Correctness and performance are both important goals in rocPRIM. Because of this, new changes should include +both test and benchmark coverage. Tests and benchmarks should be broad enough to ensure that code runs correctly +and performs well across a variety of input types and sizes. + +We also employ automated testing and benchmarking via checks that are run when a pull request is created. +These checks: +- test all algorithms for correctness across a variety of input configurations (eg. types, sizes, etc.) +- run benchmarks to check for performance degredation +- test the change on various OS platforms (Ubuntu, RHEL, etc.) +- build and run the code on different GPU architectures (MI-series, Radeon series cards, etc.) + +## Code Structure ## + +rocPRIM is a header-only library. Library code lives inside of /rocprim/include. +Algorithms are organized by the level-of-scope at which they operate. For example, +the following subdirectories (inside /rocprim/include/rocprim/) are organized by +hardware-level scope: +* device/ contains headers for device-level algorithms +* block/ contains headers for block-level algorithms +* warp/ contains headers for warp/wavefront-level algorithms. + +The following subdirectories contain supporting code: +* detail/ - utility functions and structs for the internal state of algorithms +* intrinsics/ - specialized intrinsic functions (eg. atomics, warp-shuffling, bit manipulation, etc.) +* iterator/ - contains the iterators that are used to interact with most algorithms in the library +* thread/ - primitive single-threaded algorithms (search, scan, etc.), low-level thread load and store operations +* types/ - contains a number of convenience types used in the library (eg. for storing future values, compile-time integer sequences, etc.) + +Algorithms often perform better if their launch parameters (number of blocks, block size, items per thread, etc.) are tailored for the particular architecture they are run on. +rocPRIM achieves this by passing structs called configs to algorithms when they are run. A config struct encapsulates all the information that's needed to run a particular algorithm +in the most performant way for a specific device. You can find configs for a number of algorithms in the device/detail/config/ directory. + +## 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