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.

pytest

Run Export Test Suite

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

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

Lint: Checks code style with Ruff and Black.
Test: Runs pytest with coverage enforcement (80% threshold), using a PostgreSQL service. Uploads coverage.xml and pytest-report.xml artifacts.
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:

# 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!

2.2 KiB Raw Blame History