82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# 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!
|