# Contributing to cwt

Thanks for your interest in contributing to cwt! This guide will help you get started.

## Development Setup

### Prerequisites

- **Rust** (stable, 2021 edition)
- **git** (with worktree support)
- **tmux**

### Using Nix (recommended)

The project includes a Nix flake that provides a complete development environment:

```sh
nix develop
```

This gives you Rust toolchain, `rust-analyzer`, `cargo-watch`, `cargo-edit`, plus `git` and `tmux`.

### Manual Setup

```sh
git clone https://github.com/0dragosh/cwt.git
cd cwt
cargo build
cargo test
```

## Making Changes

1. **Fork and clone** the repository
2. **Create a branch** from `main` for your changes
3. **Make your changes** -- keep commits focused and atomic
4. **Run checks** before submitting:

```sh
cargo clippy            # Lint -- must pass with zero warnings
cargo test              # Run the test suite
cargo fmt --check       # Check formatting
```

5. **Open a pull request** against `main`

## Code Conventions

- Use `anyhow::Result` for application-level errors
- Use `thiserror` for error enums in library-style modules (git, tmux, config, state)
- All git operations go through `src/git/commands.rs` -- never shell out to git from other modules
- All tmux operations go through `src/tmux/pane.rs`
- The TUI event loop is async (tokio) -- keep it non-blocking
- Follow existing code style; `cargo fmt` is enforced in CI

## Project Structure

```
src/
  main.rs          # CLI parsing, TUI bootstrap
  app.rs           # App state, event loop, rendering
  config/          # TOML config loading
  state/           # JSON state persistence
  git/             # Git worktree, branch, diff ops
  worktree/        # Worktree CRUD, handoff, snapshots
  session/         # provider session launcher + tracker
  tmux/            # tmux pane management
  hooks/           # Unix socket listener, hook scripts
  forest/          # Multi-repo config + index
  orchestration/   # Task dispatch, issue import, broadcast
  ship/            # PR creation, CI status
  env/             # Container support, ports, resources
  remote/          # SSH remote host management
  ui/              # ratatui widgets and dialogs
```

## Testing

Integration tests live in `tests/integration.rs` and create temporary git repos for isolation. Run them with:

```sh
cargo test
```

When adding new features, add corresponding integration tests. Tests should:
- Create a temp directory with `tempfile::tempdir()`
- Initialize a git repo in it
- Exercise the feature via CLI commands or library calls
- Assert on state files, git state, or command output

## Reporting Issues

- Use [GitHub Issues](https://github.com/0dragosh/cwt/issues)
- Include your OS, Rust version, and `cwt --version` output
- For bugs: steps to reproduce, expected vs actual behavior
- For features: describe the use case and how you'd expect it to work

## License

By contributing, you agree that your contributions will be licensed under the MIT License.
