CONTRIBUTING.md

Contributing

See DEVENV.md for prerequisites and environment setup.

Building

# Build the CLI binary
cargo build

# Run it locally
cargo run -- create --project TEST --title "Hello" --agent dev

Testing

# Run Rust unit tests
cargo test

# Run Cram integration tests
uv run cram tests/

# Run a single Cram test file
uv run cram tests/test-create.t

# Update expected output in-place after intentional changes
uv run cram -i tests/

Integration tests live in tests/*.t using the Cram framework. Each .t file sources tests/setup.sh, which builds the binary, adds it to PATH, and sets WQ_DATA_DIR to a per-test temporary directory for isolation.

Ticket tracking

This project uses itself to manage its own tickets. To see items available to work on:

cargo run -- list

For full usage information:

cargo run -- --help

Git hooks

A pre-commit hook auto-runs cargo fmt on staged Rust files. Enable it with:

git config core.hooksPath .githooks

Formatting and linting

cargo fmt
cargo clippy

Project layout

src/
  main.rs          Command enum and CLI entrypoint (structopt)
  config.rs        .wqconfig loading, agent resolution, project validation
  store.rs         Filesystem persistence (tickets, events, state)
  models/
    ticket.rs      Ticket, TicketState, Priority
    event.rs       Event log model
    state.rs       Workspace state (key counters)
  commands/        Subcommand implementations (one per file)
    ...
    list.rs
    update.rs
    ...
tests/
  setup.sh         Shared test harness
  *.t              Cram integration tests (one per command)