Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (70 loc) · 3.12 KB

CONTRIBUTING.md

File metadata and controls

98 lines (70 loc) · 3.12 KB

Contributing

Arco is developed as a workspace so Rust crates, the Python-facing API surface, and tooling can evolve together. Before opening a PR, sync your branch with the latest main so manifests, docs, and active work stay aligned.

Development workflow

Use workspace just targets as the default contributor entry point. This repository requires just >= 1.43.0 because the root justfile uses recipe group attributes unsupported by older releases.

If needed, install a compatible version with:

cargo install just --locked --version 1.43.0

Use workspace just targets as the default contributor entry point:

just fmt
just clippy
just check

Treat clippy and compiler warnings as errors and fix them immediately.

For a full local gate before PR creation:

just ci

For Python commands, use uv consistently:

uv run pytest

If you touch Python bindings or Python test harnesses, keep execution under uv run so environments and dependency resolution stay reproducible.

GitHub automation

The repository ships GitHub Actions for package validation and release:

  • CI runs install/import smoke tests for built wheels across Python 3.10-3.14, validates source-distribution installation, and runs docs doctests.
  • release-please runs on main, manages release PRs, creates tags and draft GitHub Releases, then dispatches cargo-dist-release.yml and publishes to PyPI.
  • cargo-dist-release.yml builds CLI binaries and installers, uploads them to the draft GitHub Release, and publishes it.
  • Releases follow one platform version stream (arco) that updates workspace and Python package versions together.
  • arco publishes artifacts and releases; Rust crates are internal and versioned as part of the same platform release.
  • Shared package smoke logic lives in scripts/python_package_smoke.py.
  • For policy and operator guidance, use RELEASE_POLICY.md as the source of truth.

Testing

Use targeted tests first, then broaden based on risk:

  • Run tests for the crates and modules you changed.
  • Add regression tests for every bug fix.
  • Prefer realistic unit and end-to-end coverage over mock-heavy tests.
  • When touching optimization plumbing, include cases that exercise memory behavior and hot paths.
  • For benchmark-sensitive changes, gate regressions against a baseline artifact: just bench-gate <baseline.jsonl> <candidate.jsonl> <duration_pct> <memory_pct>.

Suggested baseline command:

just test

And when Python tests are present:

uv run pytest

Call out any skipped suites, feature flags, or known test gaps in the PR description.

Documentation updates

Documentation ships with behavior changes.

  • If docs do not exist for a feature, the feature is not complete.
  • Update README.md for user-facing behavior and onboarding changes.
  • Update AGENTS.md when contributor workflow or engineering rules change.
  • Keep architecture and design docs in sync if you introduce new docs directories (for example docs/ or rfd/).

Include reproduction or validation steps in docs when they help others verify the change quickly.