Contributing

Want to help out with behave-django? Cool! Here’s a quick guide to do just that.

Preparation

Fork the behave-django repository, then clone it:

$ git clone git@github.com:your-username/behave-django.git

Ensure Tox is installed. We use it to run linters, run the tests and generate the docs:

$ pip install tox

If you use uv, install Tox with the tox-uv plugin:

$ uv tool install tox --with tox-uv

uv also allows you to easily install several Python versions in parallel, which is handy to help us test against all supported Pythons, e.g.

$ uv python install 3.14 --preview --default

Essentials

Make sure the tests pass. The @failing tag is used for tests that are supposed to fail. The @requires-live-http tag is used for tests that can’t run with --simple flag. See the [testenv] section in tox.ini for details.

$ tox list               # show all Tox environments
$ tox -e py314-django60  # run just a single environment
$ tox                    # run all linting and tests

Getting your hands dirty

Start your topic branch:

$ git switch -c your-topic-branch

Make your changes. Add tests for your change. Make the tests pass:

$ tox -e py-django52

Finally, make sure your tests pass on all the configurations behave-django supports. This is defined in tox.ini. The Python versions you test against need to be available in your PATH.

$ tox

You can choose not to run all tox tests and let the CI server take care about that. In this case make sure your tests pass when you push your changes and open the PR.

Code style

We use Ruff to govern our code style. ruff check and ruff format are executed with Tox and run over the code also on the CI server.

$ tox -e lint,format

To fix formatting complaints conveniently, you can run Ruff over a specific file or the entire code base like this:

$ tox -e format -- .

You can find and adapt the Ruff configuration for checks and formatting in pyproject.toml.

Writing tests

The tests folder contains:

• Unit tests (in tests/unit)

• Feature tests (in tests/acceptance)

• A minimal Django project consisting of the directories test_project and test_app, and the inevitable manage.py module. This Django project is used for the feature tests. It also serves as an example for how to use behave-django.

When you run the tests with Tox both the unit tests and the feature tests are executed, and test coverage is measured.

$ tox -e py-django52

Documentation changes

If you make changes to the documentation generate it locally and take a look at the results. Sphinx builds the output in docs/_build/.

$ tox -e docs
$ python -m webbrowser -t docs/_build/html/index.html

Finally

Push to your fork and submit a pull request.

To clean up behind you, you can run:

$ tox -e clean