Skip to content

Commit c7ab3ac

Browse files
umfranzwyhuiYH
umfranzw
and
yhuiYH
authored
Add Contribution Readme (#464)
* Add Contribution Readme Add a CONTRIBUTING.md file that contains information users will need if they want to contribute to the repository. This is based on the template located here: https://github.com/ROCm/.github/blob/main/docs/templates/contributing_template.md * Update CONTRIBUTING.md --------- Co-authored-by: Young Hui - AMD <[email protected]>
1 parent e25052a commit c7ab3ac

File tree

1 file changed

+107
-5
lines changed

1 file changed

+107
-5
lines changed

Diff for: ‎CONTRIBUTING.md

+107-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,113 @@
1-
# Contributing to rocRAND
1+
<head>
2+
<meta charset="UTF-8">
3+
<meta name="description" content="Contributing to rocRAND">
4+
<meta name="keywords" content="ROCm, contributing, rocRAND">
5+
</head>
26

3-
## Pull-request guidelines
4-
* target the **develop** branch for integration
7+
# Contributing to rocRAND #
8+
9+
We welcome contributions to rocRAND. Please follow these details to help ensure your contributions will be successfully accepted.
10+
11+
## Issue Discussion ##
12+
13+
Please use the GitHub Issues tab to notify us of issues.
14+
15+
* Use your best judgement for issue creation. If your issue is already listed, upvote the issue and
16+
comment or post to provide additional details, such as how you reproduced this issue.
17+
* If you're not sure if your issue is the same, err on the side of caution and file your issue.
18+
You can add a comment to include the issue number (and link) for the similar issue. If we evaluate
19+
your issue as being the same as the existing issue, we'll close the duplicate.
20+
* If your issue doesn't exist, use the issue template to file a new issue.
21+
* When filing an issue, be sure to provide as much information as possible, including script output so
22+
we can collect information about your configuration. This helps reduce the time required to
23+
reproduce your issue.
24+
* Check your issue regularly, as we may require additional information to successfully reproduce the
25+
issue.
26+
* You may also open an issue to ask questions to the maintainers about whether a proposed change
27+
meets the acceptance criteria, or to discuss an idea pertaining to the library.
28+
29+
## Acceptance Criteria ##
30+
31+
The rocRAND project provides functions that generate pseudorandom and quasirandom numbers. The rocRAND library is implemented in the [HIP](https://github.com/ROCm/HIP) programming language and optimized for AMD's latest discrete GPUs. It is designed to run on top of AMD's [ROCm](https://rocm.docs.amd.com/) runtime, but it also works on CUDA-enabled GPUs.
32+
33+
Performance and statistical accuracy are important in rocRAND.
34+
To protect against regressions, when a pull request is created, a number of automated checks are run. These checks:
35+
- test the change on various OS platforms (Ubuntu, RHEL, etc.)
36+
- run on different GPU architectures (MI-series, Radeon series cards, etc.)
37+
- run benchmarks to check for performance degredation
38+
39+
In order for change to be accepted:
40+
- it must pass all of the automated checks
41+
- it must undergo a code review
42+
43+
The GitHub "Issues" tab may also be used to discuss ideas surrounding particular features or changes, before raising pull requests.
44+
45+
## Code Structure ##
46+
47+
Library code is located inside the library/ directory. It contains two subdirectories:
48+
* include/ contains header files that can be included in projects using rocRAND.
49+
There is a separate header for each RNG engine and statistical distribution.
50+
* src/ contains the RNG implementations
51+
52+
Other directories in rocRAND include:
53+
* benchmark/ code for benchmarking engines and distributions is located here
54+
* docs/ contains files used to generate the rocRAND API documentation
55+
* python/ contains examples that demonstrate how rocRAND can be loaded and using in Python
56+
* scripts/ contains utility scripts for things like formating code and tuning config
57+
* test/ contains tests for the rocRAND API
58+
* tools/ contains code that helps generate the precomputed constants used by some generators
59+
60+
## Coding Style ##
61+
62+
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.
63+
64+
To format a file, use:
65+
66+
```
67+
/opt/rocm/hcc/bin/clang-format -style=file -i <path-to-source-file>
68+
```
69+
70+
To format all files, run the following script in rocRAND directory:
71+
72+
```
73+
#!/bin/bash
74+
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
75+
```
76+
77+
Also, githooks can be installed to format the code per-commit:
78+
79+
```
80+
./.githooks/install
81+
```
82+
83+
## Pull Request Guidelines ##
84+
85+
Our code contribution guidelines closely follows the model of [GitHub pull-requests](https://help.github.com/articles/using-pull-requests/).
86+
87+
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.
88+
Releases are cut to release/rocm-rel-x.y, where x and y refer to the release major and minor numbers.
89+
90+
### Deliverables ###
91+
92+
Additional things to consider when creating a pull request:
593
* ensure code builds successfully
6-
* do not break existing test cases
7-
* new functionality will only be merged with new unit tests
94+
* check to make sure that your change does not break existing test cases
95+
* ensure that new code has test coverage
896
* new unit tests should integrate within the existing [googletest framework](https://github.com/google/googletest/blob/master/googletest/docs/Primer.md)
997
* tests must have good code coverage
1098
* code must also have benchmark tests, and performance must be acceptable to maintainers
1199

100+
### Process ###
101+
102+
After you create a PR, you can take a look at a diff of the changes you made using the PR's "Files" tab.
103+
104+
PRs must pass through the checks and the code review described in the [Acceptance Criteria](#acceptance-criteria) section before they can be merged.
105+
106+
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
107+
to view logs associated with a check if it fails.
108+
109+
During code reviews, another developer will take a look through your proposed change. If any modifications are requested (or further discussion about anything is
110+
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.
111+
When a modification request has been completed, the conversation thread about it will be marked as resolved.
112+
113+
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.

0 commit comments

Comments
 (0)