Development Guide

Development Guide

Setup

git clone https://github.com/UtshaBasak/Prohori.git
cd Prohori
uv sync                       # creates .venv with the package and all dev tools
uv run pre-commit install     # runs checks on every commit

Everyday commands

Task	Command
Lint	uv run ruff check .
Auto-fix and format	uv run ruff check --fix . then uv run ruff format .
Type check (strict)	uv run mypy
Tests	uv run pytest
Tests with coverage	uv run pytest --cov
All pre-commit hooks	uv run pre-commit run --all-files
Build wheel and sdist	uv build

A Makefile wraps the same commands for Linux/macOS users; nothing requires make.

Toolchain

Tool	Role
uv	Environments and the lock file (uv.lock)
Hatchling	Build backend
Ruff	Linting (including security rules) and formatting
mypy	Strict static typing for src/ and tests/
pytest, pytest-cov, Hypothesis	Tests, coverage (minimum 85 %), property-based tests
pre-commit, gitleaks	Local checks and secret scanning
GitHub Actions	CI on Linux and Windows for Python 3.11-3.14, CodeQL, OpenSSF Scorecard
Dependabot	Weekly dependency and action updates

Conventions

• Branches: step-NN-short-name for roadmap work; feat/..., fix/..., docs/... otherwise.
• Commits: Conventional Commits.
• Code: fully typed, pathlib for paths, timezone-aware UTC datetimes, no eval, safe YAML only.
• Dependencies: the base install stays small; heavy dependencies go behind extras.
• Changelog: every user-visible change adds a line under [Unreleased] in CHANGELOG.md.
• Decisions: significant design choices get an entry in docs/DECISIONS.md.

Data rules

Never commit secrets, datasets, model binaries or real personal data. Sample files are synthetic and use documentation IP ranges only: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32.

See also CONTRIBUTING.md.