bltz 0.4.0

A fast terminal email client
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# Contributing to Bltz

Thank you for your interest in contributing to Bltz! This document provides guidelines and instructions for contributing.

## Getting Started

### Prerequisites

- Rust 1.92 or later
- A system keyring (for credential storage)
- An email account for testing

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/Mountlex/bltz.git
   cd bltz
   ```

2. Build the project:
   ```bash
   cargo build
   ```

3. Run tests:
   ```bash
   cargo test
   ```

4. Run the application:
   ```bash
   cargo run
   ```

### Debug Mode

For development, run with debug logging:

```bash
RUST_LOG=debug cargo run
```

Logs are written to `~/.config/bltz/bltz.log`.

## Code Style

### Formatting

All code must be formatted with `rustfmt`. This is enforced in CI.

```bash
cargo fmt
```

### Linting

Code must pass `clippy` without warnings:

```bash
cargo clippy --all-targets --all-features -- -D warnings
```

### Commit Messages

- Use clear, descriptive commit messages
- Start with a verb in the imperative mood (e.g., "Add", "Fix", "Update")
- Keep the first line under 72 characters
- Reference issues when applicable (e.g., "Fix #123")

Examples:
- `Add OAuth2 support for Outlook`
- `Fix thread collapsing in inbox view`
- `Update dependencies to latest versions`

## Architecture Overview

Bltz uses an actor-based architecture with async Tokio tasks:

- **`app/`** - Application state and event loop
- **`account/`** - Multi-account management
- **`mail/`** - IMAP/SMTP clients and email threading
- **`cache/`** - SQLite caching layer
- **`ui/`** - Ratatui-based terminal UI
- **`input/`** - Keyboard handling

### Key Patterns

1. **Actor Model**: Each email account has its own IMAP actor communicating via `tokio::sync::mpsc` channels.

2. **Optimistic UI**: Flag changes update the UI immediately before server confirmation.

3. **Prefetching**: Email bodies are prefetched in the background for smooth navigation.

## Pull Request Process

1. Fork the repository and create a feature branch
2. Make your changes
3. Ensure all checks pass:
   ```bash
   cargo fmt --check
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test
   ```
4. Submit a pull request with a clear description
5. Address any review feedback

## Reporting Bugs

Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) when reporting issues. Include:

- Bltz version
- Operating system
- Steps to reproduce
- Expected vs actual behavior
- Relevant log output

## Feature Requests

Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) for suggesting new features.

## Releasing (Maintainers)

Releases are automated via GitHub Actions. To create a new release:

1. Update the version in `Cargo.toml`
2. Commit the version bump:
   ```bash
   git add Cargo.toml Cargo.lock
   git commit -m "Bump version to X.Y.Z"
   ```
3. Create and push a version tag:
   ```bash
   git tag vX.Y.Z
   git push origin main
   git push origin vX.Y.Z
   ```

The release workflow will automatically:
- Build binaries for Linux x86_64 and macOS x86_64
- Generate SHA256 checksums
- Create a GitHub release with the binaries attached

## Security

For security vulnerabilities, please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines.

## License

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