Thank you for your interest in contributing to **TRX**.
This document outlines the guidelines for contributing code, documentation, and ideas to the project.

---

# **1. Getting Started**

### **Clone the repository**

```bash
git clone https://github.com/pie-314/trx.git
cd trx
```

### **Build the project**

```bash
cargo build
```

### **Run the project**

```bash
cargo run
```

### **Run tests**

```bash
cargo test
```

Ensure the project builds without warnings before opening a pull request.

---

# **2. Project Structure**

```
src/
├── main.rs          # Application entry point & terminal setup
├── config.rs        # Configuration management
├── ui/              # Terminal UI components
│   ├── app.rs       # App state & event loop
│   ├── draw.rs      # Rendering logic
│   └── input.rs     # Input handling & debouncing
├── managers/        # Package manager backends (apt, brew, pacman, etc.)
└── fuzzy/           # Scoring-based fuzzy matching engine
```

---

# **3. Contribution Areas**

You can contribute in any of these domains:

### **Backend Integrations**

Implement or improve package manager providers (apt, dnf, brew, winget, etc.).

### **TUI Improvements**

Optimizing rendering, new widgets, theme system, layout work.

### **Fuzzy Search Engine**

Improving scoring, heuristics, performance, or incremental updates.

### **Performance Work**

Caching, async pipelines, parallel execution.

### **Bug Fixes**

Reproduce, isolate, and fix issues.

### **Documentation**

Improve README, examples, architecture docs, or this file.

---

# **4. Coding Guidelines**

### **General**

* Keep the codebase clean and idiomatic.
* Prefer pure functions in UI components.
* Avoid blocking the UI thread with heavy I/O.
* Use **OS threads** and **mpsc channels** for background tasks (no async runtime).
* Return structured errors using `ManagerError`.

### **Style**

* Follow standard Rust formatting:

```bash
cargo fmt
cargo clippy
```

(Clippy warnings should ideally be zero.)

### **Commits**

* Use clear, atomic commit messages.
* Example:

  * `feat(pacman): async metadata caching`
  * `fix(ui): prevent double redraw on search`
  * `docs: update usage section`

---

# **5. Issues & Pull Requests**

### **Issues**

Before creating an issue:

* Check if the issue already exists.
* Provide steps to reproduce.
* Include logs, platform, and version when relevant.

Labels you will commonly see:

* `good first issue`
* `help wanted`
* `backend`
* `tui`
* `fuzzy`
* `performance`

### **Pull Requests**

1. Fork the repository
2. Create a feature branch

   ```bash
   git checkout -b feature/my-improvement
   ```
3. Make your changes
4. Run tests + lint
5. Commit and push
6. Open a PR describing:

   * what changed
   * why
   * how it was tested

PRs should not include unrelated formatting changes.

---

# **6. Adding a New Package Manager Backend**

To add a new provider, implement the trait:

```rust
pub trait PackageManager {
    fn search(&self, query: &str) -> Result<Vec<Package>, ManagerError>;
    fn install(&self, pkg: &str) -> Result<(), ManagerError>;
    fn remove(&self, pkg: &str) -> Result<(), ManagerError>;
    fn update(&self, pkg: &str) -> Result<(), ManagerError>;
    fn info(&self, pkg: &str) -> Result<PackageInfo, ManagerError>;
}
```

Refer to existing backends (pacman/yay) for structure and system-call patterns.

---

# **7. Development Environment**

Recommended tools:

* Rust 1.70+
* Clippy (`rustup component add clippy`)
* Rustfmt (`rustup component add rustfmt`)
* A terminal supporting Unicode + truecolor

Optional tools:

* `cargo-expand` for macro debugging
* `cargo-insta` for snapshot testing (planned)
* `just` for project scripts (future integration)

---

# **8. Code of Conduct**

All discussions and contributions must follow respectful, constructive communication.
Harassment, discrimination, or hostile behavior is not tolerated.

---

# **9. Questions / Discussions**

Use **GitHub Issues** or **Discussions** for:

* feature proposals
* design debates
* questions about architecture
* help with contributing

---

# **10. Thank You**

Your contributions make TRX better.
Even small improvements—typos, refactors, documentation—are highly valued.

