Contributing

We welcome pull requests! This guide explains the local setup, coding standards, and review expectations so contributions land smoothly.

Environment setup

  1. Fork/clone the repository.

  2. Install dependencies with uv (recommended):

    uv sync --all-extras    # runtime + dev + images + xlsx into .venv

    or with pip:

    python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

  3. Activate your environment before running commands (source .venv/bin/activate or uv run <cmd>).

Day-to-day commands

  • Tests: uv run pytest (see Testing for marker breakdown).

  • Lint: uv run ruff check src tests (CI gates on ruff check src/).

  • Format: uv run black src tests (Black is the project formatter; run it before committing).

  • Type checking: uv run mypy src (CI gates on mypy src/ only).

  • Docs: uv run make -C docs html (requires Sphinx extras from .[dev]).

Coding standards

  • Python 3.11, Black-formatted with Ruff-enforced lint (line length 120). Use type hints everywhere. pyproject.toml sets mypy --strict as the goal, but a handful of modules still carry targeted per-module error-code overrides (see the [tool.mypy.overrides] blocks) while their typing is cleaned up, so the gate is “strict except where explicitly relaxed” rather than fully strict everywhere yet.

  • Keep modules snake_case, classes CapWords, actions/events short verbs (submit, quit).

  • Write descriptive docstrings for new public APIs—Sphinx autodoc pulls these into the reference.

  • Favor explicit imports and avoid wildcard imports.

  • When editing templates, prefer declarative stacks/frames over manual spacing; keep IDs stable for focus/state wiring.

Commit & PR expectations

  • Commits should be focused and present tense (e.g., Add spinner demo). Squash locally if you end up with WIP commits.

  • Before opening a PR, run tests, lint, mypy, and docs build; include a checklist in the PR body describing which commands you ran.

  • Provide context in the PR description: problem solved, high-level approach, any trade-offs.

  • Reference related issues and the roadmap.md backlog entry when applicable.

  • For user-facing changes (UI, docs), attach screenshots or asciinema recordings to help reviewers.

Review process

  • Expect at least one subsystem-aware reviewer (core, layout, elements, terminal, etc.).

  • Be ready to discuss performance (layout allocations, render cycles) and ergonomics (does the API fit existing patterns?).

  • Address feedback promptly—either push fixes or provide rationale for alternative approaches.

Communicating changes

  • Update docs alongside code. E.g., new elements require updates in Components, template tags in Templates & Tags, etc.

  • If you touch release-critical files (src/wijjit/__init__.py, docs/source/index.rst), mention it in the PR summary so maintainers can prioritize review.

Need help?

File an issue describing the bug/feature, or start a draft PR with questions inline. We’d rather collaborate early than rewrite late. Also consult CLAUDE.md (architecture and conventions) and roadmap.md (the post-0.1.0 backlog, with root causes for known bugs) before proposing sweeping changes.