Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (71 loc) · 2.98 KB

CONTRIBUTING.md

File metadata and controls

103 lines (71 loc) · 2.98 KB
Raw

Contributing to Batty

Thanks for your interest in contributing to Batty! This document covers everything you need to get started.

Prerequisites

  • Rust (stable toolchain)
  • tmux 3.2+
  • kanban-md (cargo install kanban-md)
  • An agent CLI: Claude Code or Codex

Development Setup

git clone https://github.com/battysh/batty.git
cd batty
cargo build
cargo test

All tests must pass before submitting a PR. The CI runs on both Ubuntu and macOS.

Making Changes

  1. Fork the repo and create a branch from main
  2. Make your changes
  3. Add or update tests for any new functionality
  4. Run cargo test and make lint locally
  5. Write a clear commit message (see below)
  6. Open a PR against main

Commit Messages

Follow this format:

<scope>: <short summary>

What: <what was implemented/changed>
Why: <why this approach was chosen>
How: <key implementation details>

Keep the first line under 72 characters. The body should give enough context that git log tells the full story.

Testing

Every module must have unit tests. Use #[cfg(test)] modules in each source file. Focus on:

  • Happy paths and error conditions
  • Prompt detection and supervisor logic (the hard part)
  • Edge cases in task/board parsing
cargo test              # run all tests
cargo test <module>     # run tests for a specific module
make lint               # clippy + rustfmt check

Code Style

  • Minimal code. Build the smallest thing that works.
  • No premature abstraction. Three similar lines > one clever abstraction.
  • Compose, don't monolith. Use existing CLI tools where possible.
  • Markdown as backend. All state in human-readable, git-versioned files.

See planning/dev-philosophy.md for the full philosophy.

AI-Assisted PRs Welcome

If you used an AI tool to help write your contribution, that's fine! Just:

  • Mark the PR as AI-assisted in the description
  • Confirm you've reviewed and tested the generated code
  • Make sure tests pass and the code follows project conventions

Reporting Bugs

Use the bug report template. Include:

  • What you expected vs. what happened
  • Steps to reproduce
  • Your OS, tmux version, and agent CLI version
  • Relevant log output (check .batty/logs/)

Requesting Features

Use the feature request template. Describe the problem you're trying to solve, not just the solution you want.

Project Structure

src/               # Rust source
docs/              # User documentation (MkDocs)
planning/          # Architecture, roadmap, philosophy
assets/            # Static assets
scripts/           # Utility scripts
.batty/kanban/     # Phase boards

Questions?

Open a discussion or file an issue. We're happy to help.