Contributing to mache

Thank you for your interest in contributing to mache! We welcome contributions of all kinds, including bug reports, feature requests, code, and documentation improvements.

How to Contribute

Bug Reports & Feature Requests: Please use GitHub Issues to report bugs or request features.
Pull Requests: Fork the repository, create a new branch for your changes, and submit a pull request (PR) to the main branch. Please provide a clear description of your changes.

Development Environment

Install pixi, a faster package manager similar to conda, if you don’t already have it:

curl -fsSL https://pixi.sh/install.sh | sh

Then, open a new terminal or shell so pixi will be in your path.

Alternatively, you can install it into a conda environment via the pixi packge on conda-forge.

Note: pixi install creates the environment but does not automatically activate it in your current shell. To use tools from the environment (like python), either run commands with pixi run ... or start a subshell with pixi shell.

Set up an isolated environment:

pixi install
pixi shell
python -m pip install --no-deps --no-build-isolation -e .

Install pre-commit hooks:
```
pre-commit install
```
This ensures code style and quality checks run automatically on each commit.

Code Style and Linting

Follow PEP8 and project code style.
The following tools are used (via pre-commit):
- ruff for linting and formatting
- flynt for f-string conversion
- mypy for type checking

If a pre-commit hook fails, fix the reported issues and recommit.

Testing

Add or update tests for new features or bug fixes.
Run the test suite before submitting a PR:
```
pytest
```

Documentation

Document all public functions and classes using docstrings.
Update the API documentation if you add or modify public APIs.

Build and preview the documentation locally:

cd docs
DOCS_VERSION=test make clean versioned-html

Pull Request Checklist

[ ] User’s Guide has been updated if needed
[ ] Developer’s Guide has been updated if needed
[ ] API documentation lists any new or modified class, method, or function
[ ] Documentation builds cleanly and changes look as expected
[ ] Tests pass and new features are covered by tests
[ ] PR description includes a summary and any relevant issue references
[ ] Testing comment, if appropriate, in the PR documents testing used to verify the changes

Thank you for helping improve mache!