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
• Project Layout
• Quality Gates
• Workflow
• Conventions
• Commit Guidelines

Development Setup

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

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

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:

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:

   git checkout -b feature/<description>
   

2. Make focused, atomic changes — see Commit Guidelines.

3. Run the 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.