# 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