Skip to content

Commit 5e49cf3

Browse files
CharryWuLegNeato
CharryWu
authored and
LegNeato
committed
docs: add CONTRIBUTING.md and GitHub issue/PR templates
Add contributor guidelines covering prerequisites (CUDA, Rust nightly, cuDNN), build instructions, Windows/Linux setup notes, commit message conventions (Conventional Commits), project structure overview, and the contribution workflow. Also add GitHub issue templates (bug report, feature request) and a pull request template to standardize contributions. Closes #141 Made-with: Cursor
1 parent e91b9ce commit 5e49cf3

File tree

4 files changed

+262
-0
lines changed

4 files changed

+262
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug or unexpected behavior
4+
title: ''
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
**Describe the bug**
10+
A clear and concise description of what the bug is.
11+
12+
**To reproduce**
13+
Steps to reproduce the behavior:
14+
15+
1. ...
16+
2. ...
17+
18+
**Expected behavior**
19+
A clear and concise description of what you expected to happen.
20+
21+
**Environment**
22+
23+
- OS: [e.g. Windows 11, Ubuntu 22.04]
24+
- GPU: [e.g. RTX 3060]
25+
- CUDA Toolkit version: [e.g. 13.2]
26+
- cuDNN version (if applicable): [e.g. 9.x]
27+
- Rust toolchain: [output of `rustc --version`]
28+
29+
**Error output**
30+
If applicable, paste the full error message or log output.
31+
32+
**Additional context**
33+
Add any other context about the problem here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an enhancement or new feature
4+
title: ''
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
**Is your feature request related to a problem?**
10+
A clear and concise description of the problem. E.g. "I'm always frustrated when..."
11+
12+
**Describe the solution you'd like**
13+
A clear and concise description of what you want to happen.
14+
15+
**Describe alternatives you've considered**
16+
A clear and concise description of any alternative solutions or features you've considered.
17+
18+
**Additional context**
19+
Add any other context, links to CUDA documentation, or references here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Summary
2+
3+
Brief description of what this PR does and why.
4+
5+
Closes #ISSUE_NUMBER
6+
7+
## Changes
8+
9+
- ...
10+
- ...
11+
12+
## Testing
13+
14+
- [ ] `cargo build` passes
15+
- [ ] `cargo clippy --workspace` passes
16+
- [ ] Tested on: [OS, GPU, CUDA version]
17+
18+
## Notes
19+
20+
Any additional context for reviewers.

‎CONTRIBUTING.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Contributing to Rust CUDA
2+
3+
Welcome! We're glad you're interested in contributing to the Rust CUDA project. We welcome
4+
contributions from people of all backgrounds who are interested in making great software with us.
5+
6+
## Getting Help
7+
8+
For questions, clarifications, and general help:
9+
10+
1. Search existing [GitHub issues](https://github.com/Rust-GPU/rust-cuda/issues)
11+
2. If you can't find the answer, open a new issue or start a discussion
12+
13+
## Prerequisites
14+
15+
### Required
16+
17+
- **CUDA Toolkit** (12.x or 13.x recommended). Install from
18+
[NVIDIA's website](https://developer.nvidia.com/cuda-downloads).
19+
- **Rust nightly toolchain** -- the project pins a specific nightly via
20+
[`rust-toolchain.toml`](rust-toolchain.toml). Running any `cargo` command in the repo
21+
will automatically install the correct version if you have `rustup`.
22+
- **LLVM tools** -- installed automatically by `rustup` as part of the pinned toolchain
23+
components.
24+
- A **CUDA-capable GPU** with compute capability >= 3.0.
25+
26+
### Optional
27+
28+
- **cuDNN** -- required only if you're building the `cudnn` / `cudnn-sys` crates. Install
29+
from [NVIDIA cuDNN](https://developer.nvidia.com/cudnn).
30+
- **mdBook** -- required to build the guide locally. Install with
31+
`cargo install mdbook`.
32+
33+
### Windows-Specific Notes
34+
35+
- Ensure the CUDA Toolkit `bin` directory is on your `PATH` (e.g.
36+
`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.2\bin`).
37+
- The MSVC build tools are required. Install via
38+
[Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) with the
39+
"Desktop development with C++" workload.
40+
- If using cuDNN, place the cuDNN files in your CUDA Toolkit directory or set
41+
`CUDNN_PATH` to point to the cuDNN installation.
42+
- Some crates require `advapi32` for linking (handled automatically by build scripts).
43+
44+
### Linux-Specific Notes
45+
46+
- Ensure `nvcc` is on your `PATH` and `LD_LIBRARY_PATH` includes the CUDA lib directory.
47+
- The project provides container images for CI; see
48+
`.github/workflows/ci_linux.yml` for reference.
49+
50+
## Building
51+
52+
Build the entire workspace:
53+
54+
```sh
55+
cargo build
56+
```
57+
58+
Build a specific crate:
59+
60+
```sh
61+
cargo build -p cust
62+
cargo build -p cudnn
63+
```
64+
65+
Run clippy:
66+
67+
```sh
68+
cargo clippy --workspace
69+
```
70+
71+
Run tests (requires a CUDA-capable GPU):
72+
73+
```sh
74+
cargo test --workspace
75+
```
76+
77+
### Building the Guide
78+
79+
The user-facing documentation is an [mdBook](https://rust-lang.github.io/mdBook/) located
80+
in the `guide/` directory.
81+
82+
```sh
83+
# Install mdBook (one-time)
84+
cargo install mdbook
85+
86+
# Build and serve locally
87+
mdbook serve guide --open
88+
```
89+
90+
## Running Examples
91+
92+
Examples live in the `examples/` and `samples/` directories:
93+
94+
```sh
95+
# Vector addition
96+
cargo run -p vecadd
97+
98+
# Matrix multiplication (GEMM)
99+
cargo run -p gemm
100+
```
101+
102+
See [`examples/README.md`](examples/README.md) for the full list.
103+
104+
## Issues
105+
106+
### Feature Requests
107+
108+
If you have ideas for improvements, suggest features by opening a GitHub issue. Include
109+
details about the feature and describe any use cases it would enable.
110+
111+
### Bug Reports
112+
113+
When reporting a bug, make sure your issue describes:
114+
115+
- Steps to reproduce the behavior
116+
- Your platform (OS, GPU, CUDA version, Rust toolchain version)
117+
- Any error messages or logs
118+
119+
### Wontfix
120+
121+
Issues may be closed as `wontfix` if they are misaligned with the project vision or out of
122+
scope. We will comment on the issue with detailed reasoning.
123+
124+
## Contribution Workflow
125+
126+
### Finding Work
127+
128+
Start by looking at open issues tagged as
129+
[`help wanted`](https://github.com/Rust-GPU/rust-cuda/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
130+
or
131+
[`good first issue`](https://github.com/Rust-GPU/rust-cuda/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
132+
133+
Comment on the issue to let others know you're working on it.
134+
135+
### Pull Request Process
136+
137+
1. **Fork** the repository.
138+
2. **Create a new feature branch** from `main`.
139+
3. **Make your changes.** Ensure there are no build errors by running `cargo build` and
140+
`cargo clippy --workspace` locally.
141+
4. **Open a pull request** with a clear title and description of what you did.
142+
5. A maintainer will review your pull request and may ask you to make changes.
143+
144+
### Commit Messages
145+
146+
This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
147+
specification. Each commit message should have the format:
148+
149+
```
150+
<type>(<scope>): <description>
151+
```
152+
153+
**Types:** `feat`, `fix`, `docs`, `chore`, `ci`, `test`, `refactor`, `perf`, `style`
154+
155+
**Scopes** (common examples): `cust`, `cudnn`, `cudnn-sys`, `cust_raw`, `cuda_std`,
156+
`nvvm`, `vecadd`, `guide`, `windows`
157+
158+
**Examples:**
159+
160+
```
161+
feat(cudnn): add batch normalization forward/backward
162+
fix(cust_raw): correct Windows CUDA path discovery
163+
docs(guide): add Windows getting-started section
164+
ci(windows): include vecadd in workspace build
165+
```
166+
167+
## Project Structure
168+
169+
| Directory | Description |
170+
| --- | --- |
171+
| `crates/cust` | High-level safe wrapper around the CUDA Driver API |
172+
| `crates/cust_core` | Core `DeviceCopy` trait shared between host and device |
173+
| `crates/cust_raw` | Low-level `bindgen` bindings to CUDA SDK |
174+
| `crates/cudnn` | Type-safe cuDNN wrapper |
175+
| `crates/cudnn-sys` | Low-level `bindgen` bindings to cuDNN |
176+
| `crates/cuda_std` | GPU-side standard library |
177+
| `crates/cuda_std_macros` | Proc macros (`#[kernel]`, `#[gpu_only]`, etc.) |
178+
| `crates/cuda_builder` | Build-time helper for compiling GPU kernels |
179+
| `crates/rustc_codegen_nvvm` | Custom rustc backend targeting NVVM/PTX |
180+
| `crates/nvvm` | Wrapper around NVIDIA's libNVVM |
181+
| `crates/blastoff` | cuBLAS bindings |
182+
| `examples/` | Example programs |
183+
| `samples/` | Ports of NVIDIA CUDA samples |
184+
| `guide/` | mdBook source for the Rust CUDA Guide |
185+
186+
## Licensing
187+
188+
This project is dual-licensed under Apache-2.0 or MIT, at your discretion. Unless you
189+
explicitly state otherwise, any contribution intentionally submitted for inclusion in the
190+
work shall be dual-licensed as above, without any additional terms or conditions.

0 commit comments

Comments
 (0)