smath/CONTRIBUTING.md

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:

nix develop

You can also run direnv allow if you have direnv installed and configured.

Option 2: Local toolchain

Requirements:

• C++23-capable compiler
• CMake (3.15+)
• Ninja (recommended)

Configure and build

cmake -S . -B build -G Ninja -DSMATH_BUILD_TESTS=ON -DSMATH_BUILD_EXAMPLES=ON
cmake --build build

Running tests

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:

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