CONTRIBUTING.md

# Contributing to Multilingual-ABSA

Thanks for taking the time to contribute! This document outlines the workflow,
tooling, and conventions for building and shipping changes to this repository.

## Table of Contents

- [Development Setup](#development-setup)
- [Project Layout](#project-layout)
- [Quality Gates](#quality-gates)
- [Workflow](#workflow)
- [Conventions](#conventions)
- [Commit Guidelines](#commit-guidelines)

## Development Setup

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

Install the pre-commit hooks (optional but recommended):

```bash
pre-commit install
```

## Project Layout

```
api/            # FastAPI REST service (routes, middleware, services, tasks, models, schemas)
src/absa/       # Core ML library (data, models, evaluation, training, utils) — src-layout
frontend/       # Streamlit dashboard
scripts/        # Operational/one-off utility scripts
notebooks/      # Exploration & Colab training notebooks
tests/          # Pytest suite (api/, web/, unit/)
docs/           # Project documentation
docker/         # Container definitions & compose files
monitoring/     # Prometheus / Grafana configuration
data/           # Datasets (DVC-tracked)
models/         # Model artifacts (DVC-tracked)
```

## Quality Gates

Every change must pass all of the following before being merged:

```bash
make lint        # ruff check api src/absa tests
make typecheck   # mypy api src/absa
make security    # bandit -r api src/absa
make test        # pytest
```

## Workflow

1. **Fork** the repository and create a branch from `main`:

   ```bash
   git checkout -b feature/<description>
   ```

2. Make focused, atomic changes — see [Commit Guidelines](#commit-guidelines).

3. Run the [quality gates](#quality-gates) locally.

4. Open a pull request describing **what** changed, **why**, and how you
   verified it. Reference any related issues.

## Conventions

- **Python** — target 3.10+. Format/lint is enforced by `ruff` (120-char lines,
  `E`, `F`, `I`, `N`, `W` rule set). Type hints are checked by `mypy`.
- **Imports** — absolute imports only (`from absa.data import ...`,
  `from api.routes import ...`); never rely on `sys.path` hacks in library code.
- **Models vs. schemas** — SQLAlchemy ORM models live in `api/models/`;
  Pydantic request/response models live in `api/schemas/`.
- **Secrets** — never commit `.env` or real credentials. Add any new required
  environment variables to `.env.example`.
- **Data** — datasets and model weights are versioned with DVC, not git.
  Update `dvc.yaml` when preprocessing stages change.

## Commit Guidelines

- Keep commits small, focused, and logically independent.
- Use the imperative mood: "Add batch status endpoint", not "Added endpoint".
- Prefix with the area when it aids scanning, e.g. `api:`, `frontend:`,
  `data:`, `docs:`.
- Do not bundle unrelated changes (e.g. formatting + feature) in one commit.