Contributing to TALOS¶

Thank you for your interest in contributing to TALOS. This document explains how to report issues, propose features, and submit code changes.

Reporting Bugs¶

Check the existing issues to avoid duplicates.
Open a new issue with the following information:
Summary: One-line description of the problem.
Steps to reproduce: Minimal steps to trigger the bug.
Expected behavior: What should happen.
Actual behavior: What happens instead.
Environment: OS, Python version, Docker version, browser (if applicable).
Logs: Relevant log output (redact any credentials or secrets).

For security vulnerabilities, do not open a public issue. See SECURITY.md instead.

Proposing Features¶

Open an issue with the enhancement label.
Describe the use case: what problem does this solve and for whom?
Outline the proposed solution at a high level.
Note any MQTT topic, API, or database schema changes (these affect versioning).

Discussion happens in the issue before implementation begins.

Development Setup¶

See DEVELOPMENT.md for full setup instructions. The short version:

git clone https://gitlab.com/pierros/talos.git
cd talos
cp ops/.env.example ops/.env
make dev

Merge Request Process¶

Branch from master: Create a feature or fix branch.
```
git checkout -b feature/my-feature master
```
Make your changes: Follow the code style requirements below.
Write tests: All new functionality must have corresponding tests.

Run all checks locally:

make lint && make typecheck && make test

Commit with conventional commit messages (see below).
Open a merge request targeting master:
Describe what the MR does and why.
Reference any related issues (e.g., Closes #42).
Ensure CI passes.
Address review feedback: Push additional commits; do not force-push over review comments.
Merge: A maintainer will merge after approval and passing CI.

Code Style¶

Linting and Formatting¶

TALOS uses Ruff for linting and formatting. Configuration is in pyproject.toml.

ruff check .        # Lint
ruff check . --fix  # Lint with auto-fix
ruff format .       # Format

Type Checking¶

All code in shared/, core/, director/, and agent/ must pass mypy:

mypy shared/ core/

General Guidelines¶

Target Python 3.10+.
Maximum line length: 120 characters.
Use type hints for all function signatures.
Use Pydantic v2 models for MQTT payload schemas (in shared/schemas.py).
Use the Topics class in shared/topics.py for all MQTT topic strings.
Prefer logging over print() for all output.

Test Requirements¶

All existing tests must pass before a PR can be merged.
New features must include unit tests.
Bug fixes should include a regression test when feasible.
Test tiers:
make test -- Fast unit tests (required for all PRs)
pytest -m slow -- Benchmarks (run for performance-sensitive changes)
./tests/test_integration/test_e2e_docker.sh -- Full stack end-to-end (run before releases)

Commit Message Format¶

TALOS uses Conventional Commits:

<type>: <short description>

[optional body]

[optional footer]

Types¶

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Code style (formatting, no logic change)
`refactor`	Code restructuring (no feature or fix)
`test`	Adding or updating tests
`chore`	Build, CI, dependencies, tooling
`perf`	Performance improvement
`security`	Security fix or hardening

Examples¶

feat: add temperature telemetry topic for station health monitoring

fix: correct Doppler shift calculation for high-inclination orbits

docs: update MQTT topic hierarchy table in ARCHITECTURE.md

chore: upgrade paho-mqtt to 2.1.0

Breaking Changes¶

Append ! after the type for breaking changes:

feat!: rename station telemetry topics from telemetry/rot to telemetry/rotator

Code of Conduct¶

All contributors are expected to behave respectfully and professionally. Harassment, discrimination, and abusive behavior are not tolerated. Maintainers reserve the right to remove contributions or ban contributors who violate these expectations.