How to Contribute

Always happy to get issues identified and pull requests!

General considerations

Keep it small. The smaller the change, the more likely we are to accept.
Changes that fix a current issue get priority for review.
Check out GitHub guide if you've never created a pull request before.

Getting started

Fork the repo
Clone your fork
Create a branch for your changes

This last step is very important, don't start developing from master, it'll cause pain if you need to send another change later.

Testing

You'll need to run the tests using Python 3.12. We recommend using tox to run the tests. It will automatically create a fresh virtual environment and install our test dependencies, such as pytest-cookies and flake8.

We'll also run the tests on GitHub actions when you send your pull request, but it's a good idea to run them locally before you send it.

Installation

First, make sure that your version of Python is 3.12:

$ python --version
Python 3.12.2

Any version that starts with 3.12 will do. If you need to install it, you can get it from python.org.

Then install tox, if not already installed:

$ python -m pip install tox

Run the template's test suite

To run the tests of the template using the current Python version:

$ tox -e py

This uses pytest under the hood, and you can pass options to it after a --. So to run a particular test:

$ tox -e py -- -k test_default_configuration

For further information, please consult the pytest usage docs.

Run the generated project tests

The template tests are checking that the generated project is fully rendered and that it passes flake8. We also have some test scripts which generate a specific project combination, install the dependencies, run the tests of the generated project, install FE dependencies and generate the docs. They will install the template dependencies, so make sure you create and activate a virtual environment first.

$ python -m venv venv
$ source venv/bin/activate

These tests are slower and can be run with or without Docker:

Without Docker: tests/test_bare.sh (for bare metal)
With Docker: tests/test_docker.sh

All arguments to these scripts will be passed to the cookiecutter CLI, letting you set options, for example:

$ tests/test_bare.sh use_celery=y

Submitting a pull request

Once you're happy with your changes and they look ok locally, push and send send a pull request to the main repo, which will trigger the tests on GitHub actions. If they fail, try to fix them. A maintainer should take a look at your change and give you feedback or merge it.

3.1 KiB Raw Blame History