# 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
```

## Sign-off (DCO)

Every commit must be signed off by at least one (1) human contributor:

```
git commit -s
```

This adds a `Signed-off-by: Your Name <your@email>` trailer certifying that you
wrote the change (or otherwise have reviewed the commit and have the right to
submit it) and agree to contribute it under the project's license, per the
Developer Certificate of Origin (the DCO file in this repository - also at
https://developercertificate.org).

## 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