Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (74 loc) · 2.93 KB

CONTRIBUTING.md

File metadata and controls

100 lines (74 loc) · 2.93 KB
Raw

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:

nix develop

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

Manual Setup

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:
cargo clippy            # Lint -- must pass with zero warnings
cargo test              # Run the test suite
cargo fmt --check       # Check formatting
  1. 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:

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
  • 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.