docs/developer/index.en.md

Developer guide — Picarones

🇫🇷 Version française

This documentation targets developers who want to extend Picarones: add a new metric, a new narrative detector, a new glossary entry, a new translation, or write a custom benchmark module.

Architecture

Picarones uses a 3-circle architecture (manifesto in docs/explanation/architecture.md):

   Circle 3 (extras, report, cli, web)
   │
   ▼
   Circle 2 (measurements, engines, llm, pipelines, modules)
   │
   ▼
   Circle 1 (core)

Strict dependency rule: imports only flow from outer to inner. No shim — a module has a single canonical location.

Extension points

What	Reference doc
Add a typed metric (registered for a junction)	narrative-engine.en.md (parallel pattern)
Add a narrative detector + template	narrative-engine.en.md
Enrich the contextual glossary	extending-glossary.en.md
Add a UI translation (FR/EN/...)	extending-i18n.en.md
Write a custom benchmark module (axis B)	../user/writing-a-pipeline-module.md
Module policy (manifest + audit)	module-policy.md
Documentation consistency contract	doc-consistency.md

Running tests

pip install -e ".[dev,web]"
pytest tests/ -q --tb=short

The full suite runs in ~3 minutes. Use pytest tests/<subdir>/ to focus on a domain. Tests marked network are excluded by default (pytest -m network to include them).

Code style

• ruff lints: ruff check picarones/ tests/ (config in pyproject.toml).
• mypy strict on picarones/domain/, lax elsewhere (Sprint A1).
• No except Exception: pass — replace by logger.warning("[module] degraded feature: %s", e).
• Logger per module: logger = logging.getLogger(__name__).
• No emoji in code or commit messages unless explicitly requested.

Pre-commit hooks

pip install pre-commit
pre-commit install

Replays ruff check, trailing whitespace, YAML/JSON/TOML check, secret detection, large files (>500 KB) — same gates as the CI lint job. CI also re-runs the hooks via precommit.yml to catch --no-verify bypasses.

Releasing

See docs/operations/release-process.md for the complete release procedure. Short version:

git checkout main && git pull
# Update CHANGELOG.md
git tag -a v1.2.0 -m "Picarones 1.2.0"
git push origin main v1.2.0
# The release.yml workflow handles PyPI + ghcr.io + GitHub Release.

Help and support

• Issues: https://github.com/maribakulj/Picarones/issues
• Governance: ../../GOVERNANCE.md
• Code of conduct: ../../CODE_OF_CONDUCT.md