| 1 | # Contributing to DeepSeek TUI |
| 2 | |
| 3 | Thank you for your interest in contributing to DeepSeek TUI! This document provides guidelines and instructions for contributing. |
| 4 | |
| 5 | ## Getting Started |
| 6 | |
| 7 | ### Prerequisites |
| 8 | |
| 9 | - Rust 1.88 or later (edition 2024) |
| 10 | - Cargo package manager |
| 11 | - Git |
| 12 | |
| 13 | ### Setting Up Development Environment |
| 14 | |
| 15 | 1. Fork and clone the repository: |
| 16 | ```bash |
| 17 | git clone https://github.com/YOUR_USERNAME/DeepSeek-TUI.git |
| 18 | cd DeepSeek-TUI |
| 19 | ``` |
| 20 | |
| 21 | 2. Build the project: |
| 22 | ```bash |
| 23 | cargo build |
| 24 | ``` |
| 25 | |
| 26 | 3. Run tests: |
| 27 | ```bash |
| 28 | cargo test |
| 29 | ``` |
| 30 | |
| 31 | 4. Run with development settings: |
| 32 | ```bash |
| 33 | cargo run |
| 34 | ``` |
| 35 | |
| 36 | ## Development Workflow |
| 37 | |
| 38 | ### Code Style |
| 39 | |
| 40 | - Run `cargo fmt` before committing to ensure consistent formatting |
| 41 | - Run `cargo clippy` and address all warnings |
| 42 | - Follow Rust naming conventions (snake_case for functions/variables, CamelCase for types) |
| 43 | - Add documentation comments for public APIs |
| 44 | |
| 45 | ### Testing |
| 46 | |
| 47 | - Write tests for new functionality |
| 48 | - Ensure all existing tests pass: `cargo test --workspace --all-features` |
| 49 | - Colocate unit tests beside the code they cover (standard Rust `#[cfg(test)]` |
| 50 | modules), and add integration tests under the owning crate's `tests/` |
| 51 | directory (for example `crates/tui/tests/` or `crates/state/tests/`). The |
| 52 | repository root `tests/` directory is not used |
| 53 | |
| 54 | ### Commit Messages |
| 55 | |
| 56 | Use clear, descriptive commit messages following conventional commits: |
| 57 | |
| 58 | - `feat:` New feature |
| 59 | - `fix:` Bug fix |
| 60 | - `docs:` Documentation changes |
| 61 | - `refactor:` Code refactoring |
| 62 | - `test:` Adding or updating tests |
| 63 | - `chore:` Maintenance tasks |
| 64 | |
| 65 | Example: `feat: add doctor subcommand for system diagnostics` |
| 66 | |
| 67 | ## Project Structure |
| 68 | |
| 69 | DeepSeek TUI is a Cargo workspace. The live runtime and the majority of TUI, |
| 70 | engine, and tool code currently live in `crates/tui/src/`. Smaller workspace |
| 71 | crates provide shared abstractions that are being extracted incrementally. |
| 72 | |
| 73 | ``` |
| 74 | crates/ |
| 75 | ├── tui/ deepseek-tui binary (interactive TUI + runtime API) |
| 76 | ├── cli/ deepseek binary (dispatcher facade) |
| 77 | ├── app-server/ HTTP/SSE + JSON-RPC transport |
| 78 | ├── core/ Agent loop / session / turn management |
| 79 | ├── protocol/ Request/response framing |
| 80 | ├── config/ Config loading, profiles, env precedence |
| 81 | ├── state/ SQLite thread/session persistence |
| 82 | ├── tools/ Typed tool specs and lifecycle |
| 83 | ├── mcp/ MCP client + stdio server |
| 84 | ├── hooks/ Lifecycle hooks (stdout/jsonl/webhook) |
| 85 | ├── execpolicy/ Approval/sandbox policy engine |
| 86 | ├── agent/ Model/provider registry |
| 87 | └── tui-core/ Event-driven TUI state machine scaffold |
| 88 | ``` |
| 89 | |
| 90 | See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the live data flow across |
| 91 | these crates and [DEPENDENCY_GRAPH.md](DEPENDENCY_GRAPH.md) for build ordering. |
| 92 | |
| 93 | ## Submitting Changes |
| 94 | |
| 95 | 1. Create a feature branch from `main`: |
| 96 | ```bash |
| 97 | git checkout -b feat/your-feature |
| 98 | ``` |
| 99 | |
| 100 | 2. Make your changes and commit them |
| 101 | |
| 102 | 3. Ensure CI passes: |
| 103 | ```bash |
| 104 | cargo fmt --check |
| 105 | cargo clippy |
| 106 | cargo test |
| 107 | ``` |
| 108 | |
| 109 | 4. Push your branch and create a Pull Request |
| 110 | |
| 111 | 5. Describe your changes clearly in the PR description |
| 112 | |
| 113 | ## Pull Request Guidelines |
| 114 | |
| 115 | - Keep PRs focused on a single change |
| 116 | - Update documentation if needed |
| 117 | - Add tests for new functionality |
| 118 | - Ensure CI passes before requesting review |
| 119 | |
| 120 | ## Shape of a Typical PR |
| 121 | |
| 122 | A well-structured PR follows a consistent pattern. Recent exemplars include: |
| 123 | |
| 124 | - **#386** — `/init` command: new `crates/tui/src/commands/init.rs` module, project-type detection, |
| 125 | AGENTS.md generation, command registration in `commands/mod.rs`, localization strings. |
| 126 | - **#389** — Inline LSP diagnostics: LSP subsystem in `crates/tui/src/lsp/`, engine hooks in |
| 127 | `core/engine/lsp_hooks.rs`, config toggle, test coverage. |
| 128 | - **#387** — Self-update: new `crates/cli/src/update.rs` module, CLI subcommand registration, |
| 129 | HTTP download + SHA256 verification + atomic binary replacement. |
| 130 | - **#393** — `/share` session URL: new `crates/tui/src/commands/share.rs`, HTML rendering, |
| 131 | `gh gist create` integration, command registration. |
| 132 | - **#343/#346** — (v0.8.5) Runtime thread/turn timeline and durable task manager refactors. |
| 133 | |
| 134 | Typically each PR touches 1–3 new files, modifies 2–5 existing files for wiring |
| 135 | (registries, dispatch matches, localization), and adds or updates tests. Changes |
| 136 | are scoped to a single feature or fix — if you discover related work that needs |
| 137 | doing, open a separate issue rather than expanding the PR scope. |
| 138 | |
| 139 | Before submitting, run: |
| 140 | ```bash |
| 141 | cargo fmt --check |
| 142 | cargo clippy --workspace --all-targets --all-features 2>&1 | head -50 |
| 143 | cargo check |
| 144 | ``` |
| 145 | |
| 146 | ## Reporting Issues |
| 147 | |
| 148 | When reporting issues, please include: |
| 149 | |
| 150 | - Operating system and version |
| 151 | - Rust version (`rustc --version`) |
| 152 | - DeepSeek TUI version (`deepseek --version`) |
| 153 | - Steps to reproduce the issue |
| 154 | - Expected vs actual behavior |
| 155 | - Relevant error messages or logs |
| 156 | |
| 157 | ## Code of Conduct |
| 158 | |
| 159 | Be respectful and inclusive. We welcome contributors of all backgrounds and experience levels. |
| 160 | |
| 161 | ## License |
| 162 | |
| 163 | By contributing to DeepSeek TUI, you agree that your contributions will be licensed under the MIT License. |
| 164 | |
| 165 | ## Questions? |
| 166 | |
| 167 | Feel free to open an issue for any questions about contributing. |
| 168 |