Add a justfile for common development tasks

[acai10]

I’d like to propose adding a justfile to provide a consistent interface for common development commands.

The project would continue using uv for Python and dependency management. just would only act as a lightweight task runner on top of the existing commands.

Example

# Install project and development dependencies
install:
    uv sync --locked

# Run the test suite
test:
    uv run pytest

# Run linting
lint:
    uv run ruff check .

# Check formatting
format-check:
    uv run ruff format --check .

# Format the code
format:
    uv run ruff format .

# Run all checks used before opening a PR
check: lint format-check test

This would allow contributors to use short, discoverable commands:

just install
just test
just check

Available tasks can be listed with:

just --list

Benefits over using uv commands directly

Using uv directly is currently simple and may remain sufficient. However, a justfile could:

• provide one documented interface for common project tasks;
• group multiple checks under a single command such as just check;
• reduce the need to remember project-specific command arguments;
• keep local development and CI commands consistent;
• make it easier to extend workflows later without changing contributor-facing commands.

uv would still handle environments, dependencies, and command execution. just would not replace it.

Benefits over a Makefile

A Makefile could provide similar aliases, but just is designed specifically as a command runner rather than a build system.

Compared with make, just generally offers:

• simpler and more readable syntax;
• better command discovery through just --list;
• fewer build-system concepts for contributors to learn;
• no accidental file-target behavior;
• clearer handling of arguments and environment variables;
• more consistent cross-platform behavior.

For example, both could define a test task, but the justfile remains focused on commands:

test:
    uv run pytest

Trade-offs

The main downside is that contributors need to install an additional tool. All underlying uv commands should therefore remain documented and usable without just.

The justfile should remain a convenience layer rather than a requirement for using the project.

Installing just

macOS

brew install just

Windows

Using Winget:

winget install --id Casey.Just --exact

Linux

Depending on the distribution:

sudo apt install just        # Ubuntu/Debian
sudo dnf install just        # Fedora
sudo pacman -S just          # Arch Linux

Alternatively, install it with Cargo:

cargo install just

Questions

• Would a justfile be useful at the current size of the project?
• Should CI also call just check, or should it continue using the underlying commands directly?
• Should just be optional, with the equivalent uv commands documented alongside it?

[AnnoDomine]

I do not think this makes sense because:

• There are to less commands in this project.
• All commands are basic commands and only a few with spezified arguments like uv run run.py.
• For make the commands more accesable, you can easy create alias. And for real, everyday commands in dev should be defined as alias.

So the integration is an overhead which brings from my perspective no benefit at the moment.

[TynK-M]

I don't think adding another abstraction is good, too many external deps. The commands are pretty basic and all in the docs.