Development Guide

This guide is for contributors who want to work on FrameX locally and keep changes aligned with the current README and book chapters.

Getting Started

Create a local environment and install the project in editable mode:

uv sync --dev

If you want to verify the runtime quickly, start the built-in echo plugin:

framex run --load-builtin-plugins echo
  1. Make your change in a feature branch.
  2. Keep code, examples, and docs consistent with the public API.
  3. Run the relevant tests before opening a pull request.
  4. Re-run formatting if a hook changes files.

The commands you will use most often are:

poe test-all

Dependency Management

Use uv to manage dependencies:

uv add requests
uv add pytest --group dev
uv remove requests
uv lock --upgrade-package requests

After dependency changes, sync the environment again:

uv sync --dev

Project Tasks

poe exposes the main project tasks:

poe help

Common tasks include:

  • style: format and fix style issues
  • lint: run style and type checks
  • test: run the fast test set
  • test-all: run the full test suite
  • build: build source and wheel packages
  • publish: publish the package to PyPI

Commit Style

This project uses short, conventional commit messages:

<type>: <message>

Common types are feat, fix, docs, refactor, test, build, and chore.

Examples:

feat: add plugin config loading example
fix: handle proxy plugin response errors
docs: update quickstart for builtin plugins

Before You Open A PR

Make sure the following are true:

  • the code runs locally
  • tests pass
  • formatting hooks pass
  • docs and examples still match the current CLI behavior

Keeping changes small and focused makes review faster and reduces accidental regressions.