Skip to content

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:

uv sync --all-extras

Secret scanning is done with TruffleHog.

For security, use of pre-commit is expected. Ensure your hooks are installed:

pre-commit install

Task running is done with just. To see all available commands:

just -l

Run tests

A just task is provided to run all tests.

just test

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.

docker compose up -d --wait

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.