Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (86 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

124 lines (86 loc) · 3.5 KB

Contributing

Thanks for contributing to Agentty.

Quickstart

git clone <repo-url>
cd agentty
cargo run # Builds and runs the 'agentty' binary

Tooling Setup

Install uv

Install uv using the official instructions: https://docs.astral.sh/uv/getting-started/installation/

curl -LsSf https://astral.sh/uv/install.sh | sh

Install prek

uv tool install prek
prek install -f

Install cargo-llvm-cov

cargo install cargo-llvm-cov

Install cargo-nextest

cargo install cargo-nextest --locked

Coverage hooks also use cargo-nextest, so install both Cargo subcommands before running the full manual hook suite locally.

Website

agentty.xyz is a Zola site stored in docs/site/ and deployed through GitHub Pages.

# Preview locally
zola serve --root docs/site

# Build static output
zola build --root docs/site

Development Checks

Use .pre-commit-config.yaml as the source of truth for all formatting, linting, test, coverage, migration, roadmap, docs-site, and dependency hygiene checks. Run the hook IDs from that file through prek; hook descriptions explain what each check covers and whether it is a manual or default hook.

Roadmap Maintenance

Use the ag-xtask roadmap digest to keep planning current before revising docs/plan/roadmap.md. The roadmap quality check is the check-roadmap hook in .pre-commit-config.yaml.

# Print a read-only planning digest from git state and the roadmap
cargo run -q -p ag-xtask -- roadmap context-digest

Run roadmap context-digest before promoting work into Ready Now, and keep only Ready Now items fully expanded in docs/plan/roadmap.md.

SQLx Offline Query Metadata

When changing SQL in crates/agentty/src/infra/db.rs, regenerate offline metadata after enabling or modifying query_as!-style queries.

(
  cd crates/agentty
  DATABASE_URL=sqlite:///tmp/agentty_db.sqlite cargo sqlx database reset -y
  DATABASE_URL=sqlite:///tmp/agentty_db.sqlite cargo sqlx prepare -- --all-targets --all-features
)

This repository expects generated crates/agentty/.sqlx/ metadata so SQLx macro queries can compile in offline mode (for example, with SQLX_OFFLINE=true).

TUI E2E Tests

TUI end-to-end tests use the testty framework to drive the real agentty binary in a PTY and assert terminal state semantically. Tests are written as Rust scenarios and can also be compiled into VHS tapes for visual screenshots.

Run the test-agentty-e2e hook from .pre-commit-config.yaml with prek instead of invoking cargo directly. The hook uses language: system, so prek preserves parent-shell environment variables when it launches cargo-nextest; set TUI_TEST_UPDATE=1 on the prek run invocation when intentionally updating snapshot baselines.

Authoring Tests

Tests are written using the scenario DSL in Rust. Each scenario defines a user journey through steps (write_text, press_key, wait_for_text, capture). Use recipe helpers like expect_selected_tab and expect_keybinding_hint instead of rebuilding locator logic from scratch.

VHS is generated by the framework — do not handwrite .tape files.

Architecture Documentation

If your PR changes module boundaries, cross-layer control flow, trait-based external boundaries, or workspace crate ownership, update:

  • docs/site/content/docs/contributing/design-architecture.md

See the Design & Architecture page for the full architecture map and change-path recipes.