Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
117 lines (79 loc) · 3.52 KB

CONTRIBUTING.md

File metadata and controls

117 lines (79 loc) · 3.52 KB

Contributing

ACP Kit uses uv for dependency management, tool execution, and workspace syncing. Use the repo commands below instead of ad hoc pip, poetry, or one-off local flows.

Prerequisites

  • Python 3.11+
  • uv
  • git

Clone And Install

git clone https://github.com/vcoderun/acpkit
cd acpkit
uv sync --all-extras

uv sync --all-extras is the simplest contributor setup. It installs the root package, workspace packages, test tools, docs tools, and the pydantic-acp adapter surface used by most development work.

If you want a narrower environment, the minimum useful setup for code contributions is:

uv sync --extra dev --extra pydantic

For docs work without the full extras set:

uv sync --extra dev --extra docs --extra pydantic --extra codex

You usually do not need to activate .venv manually because the commands below use uv run.

Pre-commit

Install hooks with:

uv run pre-commit install

Run them manually with:

uv run pre-commit run --all-files

Current hook behavior:

  • validates YAML and TOML files
  • runs uv run --extra dev ruff check --fix
  • checks that local package versions are ahead of the latest published PyPI versions
  • runs make check-coverage and make prod only for major staged changes

If ruff check --fix rewrites files, re-stage them before committing.

Common Commands

Formatting and validation:

  • make format: run ruff format
  • make check-formatted: verify formatting with ruff format --check
  • make check: run ruff check, ty check, and basedpyright
  • make all: run make format and make check

Tests and coverage:

  • make tests: run the full test suite with pytest
  • make check-coverage: enforce line and branch coverage thresholds for the adapter packages
  • make save-coverage: run the same coverage job and write the summary to COVERAGE
  • make check-matrix: run lint and type checks across the supported Python version matrix

Docs:

  • make serve: run the MkDocs dev server on 127.0.0.1:8080
  • uv run --extra docs --extra pydantic --extra codex mkdocs build --strict: run the strict docs build used in CI

Higher-cost validation:

  • make prod: run tests, format, and the multi-version check-matrix gate

Recommended Local Workflow

For most changes:

  1. Sync dependencies with uv sync --all-extras.
  2. Make your change.
  3. Run make format.
  4. Run make check.
  5. Run make tests.
  6. Run uv run pre-commit run --all-files if you want the same hook surface before commit.

Run the stricter commands when they matter:

  • If you touched adapter runtime, plan, approval, bridge, or projection code, run make check-coverage.
  • If you touched docs or README-linked docs surfaces, run uv run --extra docs --extra pydantic --extra codex mkdocs build --strict.
  • If you changed packaging, CI, or anything release-sensitive, run make prod.

Pull Requests

Before opening a pull request:

  1. Make sure your branch is up to date with main.
  2. Ensure make check and make tests pass.
  3. Run the stricter coverage or docs gates when your changes affect those surfaces.
  4. Commit with a clean pre-commit result.
  5. Push your branch and verify GitHub Actions passes.

Notes

  • Prefer uv run ... over activating the environment and calling tools directly.
  • Do not add new contributor instructions that depend on pip, poetry, pdm, or pip-tools.
  • If you change the hook configuration, reinstall hooks with uv run pre-commit install.