Guidelines
This document describes how you can get started with developing Matchbox.
Dependencies¶
Setup¶
Set up environment variables by creating a .env
file under project directory. See /environments/dev_local.env
for sensible defaults.
This project is managed by uv, linted and formated with ruff, and tested with pytest. Docker is used for local development. Documentation is build using mkdocs.
To install all dependencies for this project, run:
Secret scanning is done with TruffleHog.
For security, use of pre-commit is expected. Ensure your hooks are installed:
Task running is done with just. To see all available commands:
Run tests¶
A just task is provided to run all tests.
If you’re running tests with some other method, such as your IDE or pytest directly, you’ll need to start the local backends and mock warehouse in Docker.
Database Migrations for PostgreSQL backend¶
Migrations for the PostgreSQL backend are managed by Alembic.
Warning
Do not make alternations to the database using mechanisms other then Alembic. This will interfere with the migration scripts.
If:
- You have made an alteration to the database through the ORM code, but not yet applied it
- You have run
docker compose up
to ensure the database container is running
Then you can verify a migration script would be created (without creating one) with:
Or actually create the new migration script by running:
These commands will auto-detect the difference between the ORM and the database container.
Check src/matchbox/server/postgresql/alembic/versions/
for the new migration script and verify that the autogenerate matches your expectation. See the documentation for known failure modes.
Note
Migrations are applied automatically by the application as it spins up.
Applying migrations manually¶
Sometimes you may wish to apply your migrations manually.
In Alembic:
head
refers to the latest migration scriptbase
refer to the earliest migration script
If you modify the database and need to recover it:
Debugging¶
We have a VSCode default debugging profile called “API debug”, which allows to e.g. set breakpoints on the API when running tests. After running this profile, change your .env
file as follows:
- Change the
MB__CLIENT__API_ROOT
variable to redirect tests to use the debug port (8080
) - Disable time-outs by commenting out the
MB__CLIENT__TIMEOUT
variable
Standards¶
Code¶
When contributing to the main matchbox repository and its associated repos, we try to follow consistent standards. Python code should be:
- Unit tested, and pass new and existing tests
- Documented via docstrings, in the Google style
- Linted and auto-formatted (
just format
) - Type hinted (within reason)
- Using env files and dotenv for setting environment variables
- Structured as a Python package with
pyprojects.toml
- Using dependencies managed automatically by uv
- Integrated with justfile when relevant
- Documented, for example,
README.md
files where relevant
Git¶
We commit as frequently as possible. We keep our commits as atomic as possible. We never push straight to main, instead we merge feature branches. Before merging to main, branches are peer reviewed.
Warning
Pre-commit must be turned on. Any secrets you commit to the repo are your own responsibility.
AI¶
In order to help reviewers prioritise their time appropriately, we expect any use of AI to be declared in your PR comment.