CONTRIBUTING.md

<!--
SPDX-FileCopyrightText: 2026 Team Centurions
SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Contributing to PageParse

Thank you for your interest in contributing to PageParse! Since we are building an offline-first, CPU-only engine for parsing handwriting, we hold our code quality to high standards.

---

## Code Quality Standards

Before submitting any code changes, ensure your environment is fully compliant with our local quality gates:

1. **Linting and Formatting:**
   We enforce formatting using `ruff` and `ruff-format`. Code style rules are defined in [pyproject.toml](pyproject.toml).
   
2. **Type Safety:**
   We use strict type checking via `mypy`. All new functions and files must be fully typed.
   
3. **Security Analysis:**
   All changes undergo static security analysis using `bandit` to prevent issues like command injections or insecure library usage. We also run credential scans to ensure no secrets are checked into the repo.
   
4. **Dependency Auditing:**
   We run `pip-audit` to guarantee that no dependencies with known CVEs are imported.

---

## Development Workflow

1. **Clone and Setup:**
   ```bash
   git clone https://code.swecha.org/centurions/pageparse.git
   cd pageparse
   python -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   pre-commit install
   ```

2. **Branching Strategy:**
   - Always branch off `main`.
   - Name your branch descriptively, e.g., `feat/printed-fallback` or `fix/telemetry-memory`.

3. **Conventional Commits:**
   We enforce the **Conventional Commits** specification for all commit messages. Commits must follow this pattern:
   `<type>(<scope>): <description>`
   
   Common types include:
   - `feat`: A new feature.
   - `fix`: A bug fix.
   - `docs`: Documentation updates.
   - `style`: Code style changes (formatting, white-space, etc.).
   - `refactor`: Code reorganization without behavior change.
   - `test`: Adding or modifying tests.
   - `ci`: CI/CD or build process updates.
   - `chore`: Generic maintenance tasks.

4. **Running Quality Checks Locally:**
   Before committing, run:
   ```bash
   # Run all formatters, linters, and type-checks
   pre-commit run --all-files
   
   # Run all unit and integration tests
   pytest
   ```

5. **Submitting a Merge Request (MR):**
   Once your local checks pass, push your branch and open an MR. Ensure that the self-hosted GitLab runner completes the CI pipeline successfully.