bmrk 0.4.0

# Contributing to bmrk

Thank you for your interest in contributing to bmrk! This guide will help you get started.

## Code of Conduct

Be respectful, inclusive, and constructive.

## Ways to Contribute

### 1. Report Bugs

Found a bug? Please [open an issue](https://github.com/holgertkey/bmrk/issues/new) with:

- **Clear title**: Describe the issue concisely
- **Steps to reproduce**: Exact steps to trigger the bug
- **Expected behavior**: What should happen
- **Actual behavior**: What actually happens
- **Environment**: OS, terminal emulator, Rust version, bmrk version

### 2. Suggest Features

Have an idea? [Open an issue](https://github.com/holgertkey/bmrk/issues/new) with:

- **Use case**: Why is this feature needed?
- **Proposed solution**: How should it work?
- **Alternatives**: Other approaches considered

### 3. Improve Documentation

Documentation improvements are always welcome:

- Fix typos or unclear wording
- Add examples
- Improve formatting

### 4. Write Code

Contribute code by:

- Fixing bugs
- Implementing features
- Improving performance
- Adding tests
- Refactoring

## Development Setup

### Prerequisites

- **Rust 1.70+**: Install from [rustup.rs](https://rustup.rs/)
- **Git**
- **A modern terminal**

### Clone and Build

```bash
# Fork the repository on GitHub first

# Clone your fork
git clone https://github.com/YOUR_USERNAME/bmrk.git
cd bmrk

# Add upstream remote
git remote add upstream https://github.com/holgertkey/bmrk.git

# Build
cargo build

# Run
cargo run

# Run with arguments
cargo run -- -l
```

### Development Workflow

```bash
# Create a feature branch
git checkout -b feature/my-feature

# Make changes and test
cargo run

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Run linter
cargo clippy

# Build release
cargo build --release
```

## Project Structure

```
bmrk/
├── src/
│   ├── main.rs           # Entry point, CLI, terminal setup
│   ├── app.rs            # Application state manager
│   ├── terminal.rs       # Terminal lifecycle and event loop
│   ├── event_handler.rs  # Input processing
│   ├── ui.rs             # Rendering logic
│   ├── navigation.rs     # Tree navigation logic
│   ├── tree_node.rs      # Tree data structure
│   ├── search.rs         # Search functionality (folders and files)
│   ├── quick_jump.rs     # Tab type-ahead jump + `/` scope narrowing
│   ├── dir_index.rs      # Background-built directory index (accelerates Tab/`/`)
│   ├── bookmarks.rs      # Bookmark management
│   ├── config.rs         # Configuration management
│   ├── disks.rs          # Disk/volume information
│   ├── platform.rs       # Platform-specific utilities
│   └── theme/            # Color theme structs and presets
├── docs/                 # Documentation
├── HELP.txt              # Embedded help content (bm -h)
├── Cargo.toml            # Dependencies and metadata
├── CLAUDE.md             # Development guide
└── README.md             # Project README
```

Tests live inline in each module as `#[cfg(test)] mod tests { ... }` blocks — there is no
separate `tests/` integration-test directory.

## Architecture

bmrk follows a modular MVC-style architecture. See [Architecture](./architecture.md) for details.

**Key principles**:

1. **Separation of concerns**: Each module has a single responsibility
2. **Composition over inheritance**: `app.rs` orchestrates submodules
3. **Zero-copy when possible**: Use `Rc<RefCell<>>` for shared tree ownership
4. **Async for slow operations**: Background threads for search
5. **Graceful error handling**: Never crash, always inform the user

## Coding Guidelines

### Rust Style

- Use `cargo fmt` for formatting
- Use `cargo clippy` for linting
- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)

### Code Organization

- **Keep modules focused**: Single responsibility per module
- **Avoid `app.rs` bloat**: Create new modules instead of growing `app.rs`
- **Use descriptive names**: `handle_search_input` not `hsi`

### Error Handling

- **Use `anyhow::Result`** for ergonomic error propagation
- **Never use `unwrap()`** or `std::process::exit()` in the main code path
- **No panics**: Use `Result` or `Option`
- **Graceful degradation**: Show errors to user, don't crash

### Documentation

- All public items in the `bmrk` crate must have doc comments
- Comments in English only
- Explain *why*, not *what*

### Testing

- Write tests for new features and bug fixes
- Test edge cases (empty directories, permission errors, etc.)
- Use meaningful test names: `test_expand_collapses_all_children`

## Pull Request Process

### Before Submitting

1. Run tests: `cargo test`
2. Run clippy: `cargo clippy`
3. Run fmt: `cargo fmt`
4. Test manually: run `bm` and verify your changes
5. Update HELP.txt and docs if keybindings or behavior changed

### PR Template

```markdown
## Summary
Brief description of changes

## Motivation
Why is this change needed?

## Changes
- Specific change 1
- Specific change 2

## Testing
How was this tested?

Closes #123
```

### Review Process

1. CI runs tests, clippy, fmt
2. Maintainer reviews code
3. Address feedback
4. Once approved, PR is merged

## Getting Help

- Search [existing issues](https://github.com/holgertkey/bmrk/issues)
- Open a new issue for questions

## License

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