Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Implement Plugins

SPADE can be extended by means of plugins. See how to develop one at Extending SPADE with plugins.

Report Bugs

Report bugs at https://github.com/javipalanca/spade/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

SPADE could always use more documentation, whether as part of the official SPADE docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/javipalanca/spade/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up spade for local development.

Fork the spade repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/spade.git

Install your local copy into a virtualenv. You can use uv (recommended) or traditional virtualenv tools:

With uv (recommended):
$ cd spade/
$ uv sync --extra dev

Or with traditional tools (assuming you have virtualenvwrapper installed):
$ mkvirtualenv spade
$ cd spade/
$ pip install -e .[dev]

Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.

When you’re done making changes, check that your changes pass the linter and tests, including testing other Python versions with tox:

With uv (recommended):
$ uv run ruff check spade tests
$ uv run ruff format --check spade tests
$ uv run pytest
$ uv run tox

Or with traditional tools:
$ ruff check spade tests
$ ruff format --check spade tests
$ pytest
$ tox

If using traditional tools, make sure to install the development dependencies first with pip install -e .[dev].

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 3.9, 3.10, 3.11 and 3.12. Check https://github.com/javipalanca/spade/actions and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

With uv:
$ uv run pytest tests.test_agent

Or with traditional tools:
$ pytest tests.test_agent