mirror of
https://github.com/slendidev/smath.git
synced 2026-08-06 10:49:39 +03:00
118 lines
3.3 KiB
Markdown
118 lines
3.3 KiB
Markdown
# Contributing to smath
|
|
|
|
Welcome to `smath` contributors!
|
|
|
|
This document contains a set of guidelines to contribute to the project. If you
|
|
feel like there's a mistake or something can be improved to this document, feel
|
|
free to propose changes in a pull request.
|
|
|
|
## Philosophy
|
|
|
|
- `smath` itself should be kept header only, in a single file.
|
|
- `smath` should be simple and easy to use.
|
|
|
|
## Development setup
|
|
|
|
You can work with either Nix (recommended, same tooling used in CI) or a local CMake toolchain.
|
|
|
|
### Option 1: Nix
|
|
|
|
Make sure you have flakes enabled and then execute the following to enter the shell:
|
|
|
|
```bash
|
|
nix develop
|
|
```
|
|
|
|
You can also run `direnv allow` if you have [direnv](https://direnv.net/) installed and configured.
|
|
|
|
### Option 2: Local toolchain
|
|
|
|
Requirements:
|
|
|
|
- C++23-capable compiler
|
|
- CMake (3.15+)
|
|
- Ninja (recommended)
|
|
|
|
### Configure and build
|
|
|
|
```bash
|
|
cmake -S . -B build -G Ninja -DSMATH_BUILD_TESTS=ON -DSMATH_BUILD_EXAMPLES=ON
|
|
cmake --build build
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
## Code style
|
|
|
|
This project uses `clang-format` to maintain a consistent code style. Before opening a pull request, format changed C++ files:
|
|
|
|
```bash
|
|
git ls-files '*.hpp' '*.cpp' | xargs clang-format -i
|
|
```
|
|
|
|
## AI-assisted contributions
|
|
|
|
AI-assisted contributions are allowed, subject to the following:
|
|
|
|
- A human must be in the loop at all times. AI tools may assist, but a human
|
|
contributor must drive the work, review and understand every generated
|
|
change, and take full responsibility for it. Do not submit code you have not
|
|
read and understood.
|
|
|
|
- The assistance must be disclosed. Any commit produced with material AI help
|
|
must carry an `Assisted-by:` trailer using a format similar to the Linux
|
|
kernel's AI coding assistant format:
|
|
|
|
```
|
|
Assisted-by: AGENT_NAME:MODEL_VERSION
|
|
```
|
|
|
|
`AGENT_NAME` is the AI tool or framework (e.g. Codex, Claude, ...).
|
|
`MODEL_VERSION` is the full model identifier, all lowercase, including any
|
|
numeric, snapshot, or version suffix. Do not shorten it to the model family
|
|
(e.g. use gpt-5-5, not gpt-5; use claude-opus-4-8, not claude-opus).
|
|
|
|
- Do not add `Co-authored-by:` trailers for the AI assistant. The
|
|
`Assisted-by:` trailer already serves that purpose.
|
|
|
|
- The human contributor still signs off (see above). `Signed-off-by:` is the
|
|
human's certification of, and responsibility for, the change.
|
|
`Assisted-by:` only records which tool helped. It does not replace the sign-off or the human review.
|
|
|
|
Unreviewed, bulk, or fully-automated submissions are not accepted.
|
|
|
|
## Pull requests
|
|
|
|
- Keep changes focused and scoped to one topic.
|
|
- Add or update tests when behavior changes.
|
|
- Ensure the project builds and tests pass locally.
|
|
|
|
### Commit style
|
|
|
|
Use the commit message format: `<category>: <brief>`.
|
|
|
|
Allowed categories: `feat`, `fix`, `test`, `docs`, `ci`.
|
|
|
|
Examples:
|
|
|
|
- `feat: add as_matrix() to quaternion`
|
|
- `fix: correct mat4 approx_equal ignoring a column`
|
|
- `test: add tests for vector swizzle edge cases`
|
|
- `docs: fix typo in README.md`
|
|
- `ci: update nix build command in pull request workflow`
|
|
|
|
If a commit fixes a tracked issue, include an issue-closing footer: `Closes: #<num>` (example: `Closes: #42`).
|
|
|
|
## Reporting issues
|
|
|
|
When opening an issue, include:
|
|
|
|
- what you expected to happen
|
|
- what happened instead
|
|
- a minimal reproducible example
|
|
- compiler and platform details
|