Skip to content
Back to top
View this page
Edit this page

# Contributing

We are really happy to welcome new contributors to matridge! Before starting anything, please join our chat room to say hi and see if anyone is already working on the bug you want to fix or the feature you want to implement.

## Quickstart

To start hacking on matridge, you need to:

1. Clone the repository: `git clone https://codeberg.org/slidge/matridge`.

2. Install the required dependencies. (see below)

3. Spin up a development XMPP server for matridge to connect to. (see below)

### Easy mode: docker-compose

The easiest way to achieve 2 and 3 at the same time is to use the provided `docker-compose.yml` file. Run `docker compose up` (or `podman-compose up`) in the directory of the repository you just cloned. It will:

- spin up a prosody instance configured for development;

- launch matridge in a dedicated container, with hot code reload.

You will then be able to connect to that prosody using any XMPP client, using “test@localhost” as JID and “password” as password. We recommended gajim which lets you start a different profile than your main profile: `gajim -p slidge -c ~/.local/share/gajim-slidge`.

To avoid having to accept self-signed certificates, you can add prosody’s certificate to your local store. In debian, you can do that with:

    # download the certificate
    curl https://codeberg.org/slidge/prosody-dev-container/raw/branch/main/localhost.crt | sudo tee /usr/local/share/ca-certificates/localhost.crt
    # set the right perms
    sudo chmod 600 /usr/local/share/ca-certificates/localhost.crt
    # import it
    sudo update-ca-certificates

### Slightly harder mode: setting up a virtualenv

In some situations, developing in containers is not optimal, for instance if you want to attach an interactive debugger to the matridge process.

matridge defines its dependencies in a PEP 517-compliant `pyproject.toml` file. This means that you can use different tools to set up a virtualenv with the appropriate dependencies.

We recommend using uv which is fast and has some nice features. By running `uv sync --frozen --all-groups --all-extras`, a standard virtualenv will be installed in `./.venv`. You can then activate it with `source .venv/bin/activate` and launch `matridge --help`.

NB: you will need to set up a local XMPP server. An easy way to do that is to use the `slidge-prosody-dev` container: `docker run --network host codeberg.org/slidge/prosody-slidge-dev`. With it you will be able to launch matridge with `matridge --jid slidge.localhost --secret secret --debug --home-dir ./persistent`.

### Hacking on slidge core simultaneously

Maybe you will discover that what you want to change, add or fix is not part of matridge but part of slidge core. To modify slidge core, first you need to clone the slidge repo somewhere on your computer.

Let’s assume you cloned `slidge` in the same root dir as `matridge`, e.g., `~/src/matridge` and `~/src/slidge`. With the `docker-compose`-based dev setup, you will need to add an additional mount for the slidge dir, e.g., `../slidge:/build/slidge`. If you opted for the virtualenv solution, you can install slidge in your virtualenv in editable mode with `[uv] pip install -e ../slidge`.

## Guidelines

matridge uses these tools to ensure some level of code quality:

- mypy for static type checking,

- ruff to detect common python mistakes and enforce a consistent style,

- pytest for automated tests.

Commit messages should be in the form of conventional commits, with some additional types defined in ./commitlinx.config.js. This makes it possible to automatically generate changelogs on releases, it is worth it! We use git-cliff for this. You don’t have to install git-cliff locally, the magic happens in CI.

We recommended setting up pre-commit to ensure that these pass for each commit: `pre-commit install && pre-commit install --hook-type commit-msg`.

Make a new git branch, commit your changes, push it to your fork and open a pull request!

NB: we also accept contributions without pull requests. Just push your changes somewhere and tell us where to pull via the group chat.