Skip to content

Contributing

Setting up

pluxeo uses uv.

git clone <repository-url> pluxeo
cd pluxeo
uv sync

Everyday commands

make test         # the test suite
make lint         # ruff, ruff format --check, ty, pyrefly and mypy on src/
make format       # format and apply safe fixes
make test-cov     # coverage report
uv run nox        # tests on every supported Python (3.11 to 3.15)

A change must satisfy every checker make lint runs, not only one of them. Ruff runs with every rule selected; a rule is silenced only with a comment saying why.

Layout

src/pluxeo/
  __init__.py     the public API; everything else is private
  _manager.py     PluginManager
  _spec.py        Plugin, PluginSpec, @plugin
  _discovery.py   discovery sources
  _lifecycle.py   listeners, generator teardown
  _contracts.py   contract policy
  _dispatch.py    Pluggy markers and the inner Pluggy manager
  _async.py       the async hook caller
  _enablement.py  enablement policies
  _state.py       states and exceptions
  cli.py          pluxeo index
tests/
  a_unit/         unit tests, one module per area: test_phaseN_*.py
  b_integration/
  c_e2e/
docs/             this site

Test modules are named after the build phase that introduced the area they cover (test_phase4_dispatch.py, test_phase11_composability.py); a new test usually belongs in the module of the area it touches.

Rules a change must keep

The architecture lists the invariants; the tests enforce them. Two deserve repeating:

  • Every instance through its factory. Never instantiate a plugin class directly; call spec.factory(). A dedicated test checks this on every discovery path.
  • Hooks live iff loaded and enabled. Any change touching loading, unloading, enabling or errors must keep this true at every step, including while a plugin's cleanup runs.

Out of scope, so please do not add them speculatively: a dependency-injection container, async hook wrappers, file-system watching, multi-version plugins, hooks into build backends.

The documentation

The site is built with Zensical from docs/:

cd docs
make serve        # local preview, rebuilt on change
make build        # the static site, in docs/site/
make diagrams     # redraw the SVG diagrams from docs/diagrams/*.typ (needs typst)

Code examples on the guide pages run as written: keep them that way when changing the API.