Skip to content

Commit 61d11a9

Browse files
bratpiorkabratpiorka
authored
Merge pull request #233 from lukaszstolarczuk/contrib
Extend Contribution Guide
2 parents 1d79baa + 6472d4c commit 61d11a9

File tree

5 files changed

+227
-22
lines changed

5 files changed

+227
-22
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: Bug report
3+
about: Did you find a bug in UMF? Please let us know.
4+
labels: "bug"
5+
---
6+
<!--
7+
Before creating new issue, ensure that similar issue wasn't already created
8+
* Search: https://github.com/oneapi-src/unified-memory-framework/issues
9+
10+
Note that if you do not provide enough information to reproduce the issue, we may not be able to take action on your report.
11+
Remember this is just a minimal template. You can extend it with data you think may be useful.
12+
-->
13+
14+
<!-- fill the title of issue with short description -->
15+
16+
## Environment Information
17+
18+
- UMF version (hash commit or a tag): <!-- fill this out -->
19+
- OS(es) version(s): <!-- fill this out -->
20+
- kernel version(s): <!-- fill this out -->
21+
- compiler, libraries, and other related tools version(s): <!-- fill this out -->
22+
23+
<!-- fill in also other useful environment data -->
24+
25+
## Please provide a reproduction of the bug:
26+
27+
<!-- fill this out -->
28+
29+
## How often bug is revealed:
30+
31+
(always, often, rare) <!-- pick one if possible -->
32+
<!-- describe special circumstances -->
33+
34+
## Actual behavior:
35+
36+
<!-- fill this out -->
37+
38+
## Expected behavior:
39+
40+
<!-- fill this out -->
41+
42+
## Details
43+
44+
<!-- fill this out -->
45+
46+
## Additional information about Priority and Help Requested:
47+
48+
Are you willing to submit a pull request with a proposed change? (Yes, No) <!-- check one if possible -->
49+
50+
Requested priority: (Showstopper, High, Medium, Low) <!-- check one if possible -->

‎.github/ISSUE_TEMPLATE/feature.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: Feature
3+
about: Request a feature/enhancement
4+
labels: "enhancement"
5+
---
6+
7+
<!-- fill the title of your feature/enhancement -->
8+
9+
## Rationale
10+
11+
<!-- fill this out -->
12+
13+
## Description
14+
15+
<!-- fill this out -->
16+
17+
## API Changes
18+
19+
<!-- fill this out, if needed -->
20+
21+
## Implementation details
22+
23+
<!-- fill this out if possible -->
24+
25+
## Meta
26+
27+
<!-- fill this out -->

‎.github/ISSUE_TEMPLATE/question.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: Question
3+
about: Do you have question regarding UMF? Don't hesitate to ask.
4+
labels: "question"
5+
---
6+
7+
<!-- fill the title with short version of your question -->
8+
9+
## Details
10+
11+
<!-- fill this out -->

‎CONTRIBUTING.md

Lines changed: 137 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,129 @@
1-
# Contributing
1+
# Contributing to UMF (Unified Memory Framework)
2+
3+
4+
<!-- TODO: Add [Naming convention](#naming-convention) section -->
5+
- [Opening new issues](#opening-new-issues)
6+
- [Submitting Pull Requests](#submitting-pull-requests)
7+
- [Building and testing](#building-and-testing)
8+
- [Code style](#code-style)
9+
- [When my PR is merged?](#when-my-PR-is-merged)
10+
- [Extending public API](#extending-public-api)
11+
- [License](#license)
12+
- [Adding new dependency](#adding-new-dependency)
13+
14+
Below you'll find instructions on how to contribute to UMF, either with code changes
15+
or issues. All contributions are most welcome!
16+
17+
## Opening new issues
18+
19+
Please log bugs or suggestions as [GitHub issues](https://github.com/oneapi-src/unified-memory-framework/issues).
20+
21+
When reporting a bug remember about the details, at least:
22+
- version of UMF (hash of a commit or a tag),
23+
- OS and kernel,
24+
- compiler.
25+
26+
When opening a new issue you can pick a predefined type of issue. Please follow
27+
the template and fill in all the information. If your query doesn't match any of
28+
the proposed types, just pick a general issue with no template.
29+
30+
## Submitting Pull Requests
31+
32+
We take outside code contributions to UMF through GitHub pull requests.
33+
You must first create your own fork of the project and submit your changes to a branch.
34+
You can then raise a Pull Request targeting `oneapi-src/unified-memory-framework:main`.
35+
Please try to keep commits neat and in order - please squash your commits to
36+
include only relevant ones (no "fixes after review" or similar).
37+
38+
### Building and testing
39+
40+
Building commands can be found in the top-level Readme file - section
41+
["Build"](./README.md#build).
42+
43+
Before committing you should test locally if all tests and checks pass.
44+
When project is built, enter the build directory and execute:
45+
46+
```bash
47+
$ ctest --output-on-failure
48+
```
49+
50+
Any test's failure will produce error log.
51+
52+
To enable additional checks (including `-Werror` / `/WX` compilation flag), switch on CMake flag
53+
`UMF_DEVELOPER_MODE`. To read more about all available CMake options please see
54+
["CMake standard options"](./README.md#cmake-standard-options) section in the top-level Readme.
55+
56+
### Code style
57+
58+
We use `clang-format` to verify and apply code style changes. To see all rules we require,
59+
please take a look at `.clang-format` file in the root directory of this repository.
60+
61+
To enable code style checks and re-formatting, CMake option `UMF_FORMAT_CODE_STYLE` has to
62+
be switched on. You'll then have two additional CMake targets available.
63+
64+
To verify correct coding style of your changes execute (assuming `build` is your build directory):
65+
66+
```bash
67+
$ cmake -B build -DUMF_FORMAT_CODE_STYLE=ON
68+
$ cmake --build build --target clang-format-check
69+
```
70+
71+
We run this check in our Continuous Integration (CI). So, if any issues were found,
72+
the Pull Request will be blocked from merging. To apply proper formatting (meaning,
73+
to fix the issues) execute the second available CMake target - run a command:
74+
75+
```bash
76+
$ cmake --build build --target clang-format-apply
77+
78+
# Remember to review introduced changes
79+
```
80+
81+
**NOTE**: We use specific clang-format version - **15.0** is required. It can be installed,
82+
e.g., with command: `python -m pip install clang-format==15.0.7`.
83+
84+
### When my PR is merged?
85+
86+
Your Pull Request (PR) will be merged if you meet several requirements - the basic are:
87+
- The project builds properly,
88+
- All tests are executed, and no issues have been reported,
89+
- All checks pass (code style, spelling, etc.),
90+
- Additional requirements are fulfilled (e.g., see below, for a new public API function).
91+
92+
While the most of these requirements are verified via automated scripts run in
93+
Continuous Integration (CI) they are also verified with human touch - **the review**!
94+
95+
Code review has to be done by at least two UMF maintainers. The "maintainers team"
96+
is added to each PR by default, but you can also pick specific people to review
97+
your code. It may speed up a little the review process. If any issues are found by
98+
reviewers they should be fixed by the owner of the PR.
99+
100+
Now, when all GitHub Actions jobs are green, all review discussions are resolved, and
101+
you got two approvals from reviewers - you're good to go - your PR will be merged soon!
102+
103+
### Extending public API
104+
105+
When adding a new public function, you have to make sure to update:
106+
- documentation,
107+
- map files with debug symbols (both .def and .map - for Windows and Linux),
108+
- appropriate examples (to show usage),
109+
- tests.
110+
111+
<!--
112+
### Naming convention
113+
TODO: add this section and re-format whole codebase to use such convention
114+
-->
2115

3116
### License
4117

5-
<PROJECT NAME> is licensed under the terms in [LICENSE]<link to license file in repo>. By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.
118+
Unified Memory Framework is licensed under the terms in [LICENSE](./LICENSE.TXT) file. By contributing to the project,
119+
you agree to the license and copyright terms therein and release your contribution under these terms.
6120

7-
### Sign your work
121+
**NOTE:**
122+
>Each new file added to the repository has to contain the appropriate license header. To see what
123+
>such a header looks like, you can see an existing file, at best, with the same file extension
124+
>(each type of file may have slightly different formatting and/or comment convention).
8125
9-
Please use the sign-off line at the end of the patch. Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify
10-
the below (from [developercertificate.org](http://developercertificate.org/)):
126+
With your contributions to this repository you also certify the following:
11127

12128
```
13129
Developer Certificate of Origin
@@ -47,11 +163,24 @@ By making a contribution to this project, I certify that:
47163
this project or the open source license(s) involved.
48164
```
49165

50-
Then you just add a line to every git commit message:
166+
In case of any doubt, the maintainer may ask you to certify the above in writing, i.e.
167+
via email or by including a `Signed-off-by:` line at the bottom of your commit message.
51168

52-
Signed-off-by: Joe Smith <[email protected]>
169+
Please, use your real name (sorry, no pseudonyms or anonymous contributions.), e.g.:
53170

54-
Use your real name (sorry, no pseudonyms or anonymous contributions.)
171+
Signed-off-by: Joe Smith <[email protected]>
55172

56173
If you set your `user.name` and `user.email` git configs, you can sign your
57174
commit automatically with `git commit -s`.
175+
176+
### Adding new dependency
177+
178+
Adding each new dependency (including new docker image or a package) should be done in
179+
a separate commit. The commit message should be:
180+
181+
```
182+
New dependency: dependency_name
183+
184+
license: SPDX license tag
185+
origin: https://dependency_origin.com
186+
```

‎README.md

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -163,17 +163,5 @@ The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this
163163

164164
## Contributions
165165

166-
All code has to be formatted using clang-format. To check the formatting do:
167-
168-
```bash
169-
$ mkdir build
170-
$ cd build
171-
$ cmake {path_to_source_dir} -DUMF_FORMAT_CODE_STYLE=ON
172-
$ make clang-format-check
173-
```
174-
175-
Additionally, to apply code formatting do:
176-
177-
```bash
178-
$ make clang-format-apply
179-
```
166+
All contributions to the UMF project are most welcome! Before submitting
167+
an issue or a Pull Request, please read [Contribution Guide](./CONTRIBUTING.md).

0 commit comments

Comments
 (0)