Contributing¶

We can always use your help to improve Django AI Assistant! Please feel free to tackle existing issues. If you have a new idea, please create a thread on Discussions.

Please follow this guide to learn more about how to develop and test the project locally, before opening a pull request.

Local Dev Setup¶

Clone the repo¶

git clone git@github.com:vintasoftware/django-ai-assistant.git

Set up a virtualenv, optionally set up nvm, and activate your environment(s)¶

You can use pyenv, pipenv, vanilla venvs or the tool of your choice.

For installing Node, we recommend NVM.

Install dependencies¶

Backend¶

poetry install

Frontend¶

cd frontend
npm install

Install pre-commit hooks¶

pre-commit install

It's critical to run the pre-commit hooks before pushing your code to follow the project's code style, and avoid linting errors.

Developing with the example project¶

Run the frontend project in build:watch mode:

cd frontend
npm run build:watch

Then follow the instructions in the example README.

Tests¶

Run tests with:

poetry run pytest

The tests use pytest-vcr to record and replay HTTP requests to AI models.

If you're implementing a new test that needs to call a real AI model, you need to set the OPENAI_API_KEY environment variable on root .env file. Then, you will run the tests in record mode:

poetry run pytest --record-mode=once

Documentation¶

We use mkdocs-material to generate the documentation from markdown files. Check the files in the docs directory.

To run the documentation locally, you need to run:

poetry run mkdocs serve

Release¶

Info

The backend and the frontend are versioned together, that is, they should have the same version number.

To release and publish a new version, follow these steps:

Update the version in pyproject.toml and frontend/package.json.
Update the changelog in CHANGELOG.md.
Open a PR with the changes.
Once the PR is merged, run the Release GitHub Action to create a draft release.
Review the draft release, ensure the description has at least the associated changelog entry, and publish it.
Once the review is publish, the Publish GitHub Action will automatically run to publish the new version to PyPI and npm. Check the logs to ensure the publication was successful.