CONTRIBUTING.md

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.

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:

   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:

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