# Contributing to Kurier

Thank you for your interest in contributing to Kurier.

To ensure a consistent and high-quality codebase, we have established the following guidelines for development, testing, and contribution. Please read this document before submitting any pull requests.

## Development Environment Setup

This project utilizes **uv** for high-performance dependency management and **Python 3.10+**.

### 1. Repository Setup
Fork the repository on GitHub and clone your fork locally:

```bash
git clone https://github.com/peteriadamgabor/kurier-py.git
cd kurier-py
```

### 2. Dependency Installation
We use `uv` to manage virtual environments and dependencies. Run the following command to sync the environment with all transport extras (RabbitMQ, Kafka, Azure) and development tools:

```bash
uv sync --all-extras --dev
```

### 3. Pre-commit Hooks
We strongly recommend installing pre-commit hooks to automatically enforce code style on every commit. This prevents CI failures by catching formatting and linting issues locally.

```bash
# Install the hooks for commits
uv run pre-commit install

# (Optional) Install the hooks for pushes
uv run pre-commit install --hook-type pre-push

# Run hooks manually on all files to check for existing issues
uv run pre-commit run --all-files
```

## Testing Guidelines

Kurier supports Python versions 3.10 through 3.13. All contributions must pass the full test suite before being accepted.

To run the tests locally:

```bash
# Run the complete test suite
uv run pytest

# Run a specific test module
uv run pytest tests/test_station.py
```

Ensure that any new features include accompanying unit tests to maintain coverage and stability.

## Code Style and Standards

We enforce a strict coding style using **Ruff**. This ensures readability and consistency across the entire library.

Before submitting a Pull Request, you must ensure your code is linted and formatted:

```bash
# Check for linting errors
uv run ruff check .

# Apply automatic formatting
uv run ruff format .
```

If you have set up the pre-commit hooks, these checks will run automatically when you attempt to commit changes.

## Workflow and Branching Strategy

To maintain a clean and linear history on the `master` branch, we adhere to the following workflow:

1.  **Branching:** Always create a new branch for your work. Do not commit directly to your local `master` branch.
2.  **Linear History:** We utilize a linear git history. Please rebase your branch against `upstream/master` rather than merging `master` into your branch.
3.  **Commit Messages:** Write clear, concise commit messages that describe the "why" and "what" of your changes.

### Pull Request Process

1.  Push your changes to your fork and submit a Pull Request against the `master` branch.
2.  All Pull Requests are **squash-merged**. This combines your commits into a single, clean commit on the main branch.
3.  **CI Requirements:** Your code must pass all automated status checks (Python 3.10, 3.11, 3.12, and 3.13 builds).
4.  **Code Review:** At least one approving review from a maintainer is required before merging.

## Reporting Issues

When reporting bugs or requesting features, please use the provided **Issue Templates** on GitHub. Include all relevant environment details (Python version, OS, Transport type) and strict reproduction steps.

Thank you for helping us make Kurier better.
