# Contributing to Calminer

We welcome contributions to Calminer! If you would like to contribute, please follow these guidelines:

## Fork the Repository

Create a personal copy of the repository on your GitHub account.

## Create a Branch

Before making changes, create a new branch for your feature or bug fix.

## Make Your Changes

Implement your changes in the new branch.

## Write Tests

Ensure that your changes are covered by tests.

## Run Test Suite With Coverage

Execute the default pytest run to enforce the 80% project-wide coverage threshold and review missing lines in the terminal report.

```bash
pytest
```

## Run Export Test Suite

Before opening a pull request, run the export-focused pytest module to verify CSV/XLSX streaming endpoints.

```bash
pytest tests/test_export_routes.py
```

This ensures the API headers, download content, and modal routes remain functional.

## Submit a Pull Request

Once you are satisfied with your changes, submit a pull request to the main repository.

## Continuous Integration

Calminer uses Gitea Actions for automated testing, linting, and deployment. The CI pipeline is defined in `.gitea/workflows/cicache.yml` and runs on pushes and pull requests to the `main` and `develop` branches.

### Pipeline Stages

1. **Lint**: Checks code style with Ruff and Black.
2. **Test**: Runs pytest with coverage enforcement (80% threshold), using a PostgreSQL service. Uploads coverage.xml and pytest-report.xml artifacts.
3. **Build**: Builds Docker image and pushes to registry only on `main` branch pushes (not PRs) if registry secrets are configured.

### Workflow Behavior

- Triggers on push/PR to `main` or `develop`.
- Linting must pass before tests run.
- Tests must pass before build runs.
- Coverage below 80% fails the test stage.
- Artifacts are available for PR inspection.
- Docker push occurs only for main branch commits with valid registry credentials.

### Local Testing

To replicate CI locally:

```bash
# Install test deps
pip install -r requirements-test.txt

# Run linting
ruff check .
black --check .

# Run tests with coverage
pytest --cov=. --cov-report=term-missing --cov-fail-under=80

# Build image
docker build -t calminer .
```

Thank you for your interest in contributing to Calminer!