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

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