Spaces:
Running
Running
File size: 3,041 Bytes
95cbd83 d0a3fab 95cbd83 2b782d0 95cbd83 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | <!-- translation: machine + human review pending -->
<!-- canonical: docs/developer/index.md (FR) -->
# Developer guide — Picarones
> 🇫🇷 [Version française](index.md)
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`](../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`](narrative-engine.en.md) (parallel pattern) |
| Add a narrative detector + template | [`narrative-engine.en.md`](narrative-engine.en.md) |
| Enrich the contextual glossary | [`extending-glossary.en.md`](extending-glossary.en.md) |
| Add a UI translation (FR/EN/...) | [`extending-i18n.en.md`](extending-i18n.en.md) |
| Write a custom benchmark module (axis B) | [`../user/writing-a-pipeline-module.md`](../user/writing-a-pipeline-module.md) |
| Module policy (manifest + audit) | [`module-policy.md`](module-policy.md) |
| Documentation consistency contract | [`doc-consistency.md`](doc-consistency.md) |
## Running tests
```bash
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
```bash
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`](../operations/release-process.md)
for the complete release procedure. Short version:
```bash
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`](../../GOVERNANCE.md)
- Code of conduct: [`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md)
|