# Contributing to raisfast

Thank you for your interest in contributing to raisfast!

## Status

raisfast is in **early alpha**. The codebase evolves rapidly and APIs may change without notice. We appreciate your patience and willingness to contribute at this stage.

## How to Contribute

### Bug Reports

- Open a [GitHub Issue](https://github.com/snkzhong/raisfast/issues/new)
- Include: Rust version, OS, feature flags used, steps to reproduce, expected vs actual behavior
- Check existing issues before filing a new one

### Feature Requests

- Open a GitHub Issue with the `feature-request` label
- Describe the use case, not just the solution
- Indicate if you're willing to implement it

### Pull Requests

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes
4. Ensure all checks pass:
   ```bash
   cargo fmt --check
   cargo clippy --features "db-sqlite plugin-all search-tantivy" -- -D warnings
   cargo test --features "db-sqlite plugin-all search-tantivy" -- --test-threads=1
   ```
5. Submit a pull request

## Development Setup

### Prerequisites

- Rust 1.85+ (edition 2024)
- pnpm (for Admin UI development)
- SQLite 3.x

### Build

```bash
# Backend only
cargo build --features "db-sqlite plugin-all search-tantivy"

# Backend + Admin UI
just build-full
```

### Test

```bash
# Unit + integration tests
cargo test --features "db-sqlite plugin-all search-tantivy" -- --test-threads=1

# Lint
cargo clippy --features "db-sqlite plugin-all search-tantivy" -- -D warnings

# Format check
cargo fmt --check
```

### Admin UI Development

```bash
cd frontend/admin
pnpm install
pnpm dev    # Dev server at http://localhost:5173
pnpm build  # Production build (embedded into Rust binary)
```

## Code Style

### Rust

- `cargo fmt` and `cargo clippy` are authoritative
- Public items require `///` doc comments
- Handler → Service → Repository layering enforced; handlers must not contain business logic
- No `unsafe` code (`#![deny(unsafe_code)]` at crate root)
- No `unwrap()` / `expect()` in non-test code; use `?` or explicit error handling
- Error handling: `thiserror` for `AppError` enum at handler boundaries; `anyhow` for internal service errors
- SQL queries use `sqlx::query()` / `sqlx::query_as()` (not `!` macros) + `dialect::translate()`
- All database-specific code uses `crate::db::dialect::*` helpers for portability

### Commits

- Use clear, descriptive commit messages
- Keep PRs focused on a single concern
- Rebase on main before submitting

## Architecture

Before contributing, please read:

- `docs/guide.md` — Product and architecture specification
- `AGENTS.md` — Technical constraints and coding conventions
- `docs/serverless.md` — Serverless deployment design
- `docs/product-analysis.md` — Product positioning and roadmap

## License

By contributing, you agree that your contributions will be licensed under the same license as the module you're modifying:

- Core framework: MIT
- Commercial modules: BSL 1.1