raisfast/CONTRIBUTING.md

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
• 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:

   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

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

# Backend + Admin UI
just build-full

Test

# 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

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