Contributing¶

Contributions to jonq are welcome! Here’s how you can help.

Setting Up Development Environment¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/duriantaco/jonq.git
cd jonq

Create a virtual environment and install development dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
pre-commit install --install-hooks

To build the documentation locally, also install the docs requirements:

pip install -r docs/requirements.txt

Running Tests¶

jonq uses pytest for testing. To run tests:

pytest

Run the full test suite before opening a pull request. If you change only documentation, build the Sphinx docs as well.

Pre-Commit Hooks¶

The repository includes local pre-commit hooks for Ruff, package compilation, and a focused pre-push pytest smoke suite.

pre-commit run --all-files

Manual Testing¶

You can also use the shell scripts in the tests directory to run manual checks:

bash tests/test_simple.sh
bash tests/test_nested.sh

Contributing Code¶

Create a new branch for your feature or bugfix:
```
git switch -c feature-name
```
Make your changes and add tests for new features
Run the test suite to make sure everything passes

Commit your changes:

git commit -m "Description of your changes"

Push your branch to GitHub:
```
git push origin feature-name
```
Create a Pull Request from your fork

Coding Style¶

Please follow PEP 8 coding conventions and include docstrings for new functions and classes.

Adding Documentation¶

If you’re adding new features, please update the documentation as well. jonq uses Sphinx for documentation:

Update or add docstrings to your code
Update RST files in the docs directory if needed
Build the documentation to check your changes:
```
cd docs
make html
```
The documentation will be built in docs/build/html.

Reporting Issues¶

If you find a bug or have a suggestion for improvement, please create an issue on the GitHub repository.

Releases¶

Maintainers publish from GitHub Releases. Before creating a release, update pyproject.toml, jonq/constants.py, and CHANGELOG.md in a release prep pull request. Publishing uses PyPI trusted publishing from the pypi GitHub environment.