CONTRIBUTING.md

Contributing to xsf

Install Pixi first. Pixi provisions the compiler toolchain and other dependencies defined in pixi.toml.

Note

The documented commands below have only been tested on macOS and Linux.

Clone the repository

Fork the repository, then set origin to your fork and add upstream:

git clone https://github.com/your-github-id/xsf.git
cd xsf
git remote add upstream https://github.com/scipy/xsf.git

Check remotes with:

git remote -v

You should see:

origin  https://github.com/your-github-id/xsf.git (fetch)
origin  https://github.com/your-github-id/xsf.git (push)
upstream    https://github.com/scipy/xsf.git (fetch)
upstream    https://github.com/scipy/xsf.git (push)

To sync your branch with upstream main:

git fetch upstream
git checkout main
git merge upstream/main

Run tests

Run the default C++ test workflow:

pixi run tests

For incremental local work, you can run the steps separately:

pixi run configure-tests
pixi run build-only
# '4' here determines the number of workers used
pixi run tests-only 4

Useful variants:

• Rebuild after changing code: pixi run build-tests
• Debug test build with extra assertions: pixi run tests-debug

Formatting

Check formatting without modifying files:

pixi run format-dry-error

Apply formatting:

pixi run format

Coverage

Generate a local HTML coverage report with:

pixi run coverage
# or
pixi run configure-coverage
pixi run --skip-deps build-tests-cov
pixi run --skip-deps tests-only
pixi run --skip-deps coverage

The generated report is written to build/coverage_report/index.html.

For subsequent runs in the same build tree, it is usually enough to rerun:

pixi run --skip-deps tests-only
pixi run --skip-deps coverage

Pull requests

Run the relevant tests and formatting checks before opening a pull request.