# How to contribute
So, you've decided to contribute, that's great!
You can use this document to figure out how and where to start.
## Getting started
- Make sure you have a [GitHub account](https://github.com/join).
- Take a look at [existing issues](https://github.com/remysaissy/lorm/issues).
- If you need to create an issue:
- Make sure to clearly describe it.
- Including steps to reproduce when it is a bug.
- Include the version of LOrm used.
## Making changes
- Fork the repository on GitHub.
- Create a branch on your fork.
- You can usually base it on the `main` branch.
- Make sure not to commit directly to `main`.
- Make commits of logical and atomic units.
- Make sure you have added the necessary tests for your changes.
- Push your changes to a topic branch in your fork of the repository.
- Submit a pull request to the original repository.
## What to work on
We try to mark issues with a suggested level of experience (in Rust/SQL).
Where possible we try to spell out how to go about implementing the feature.
To start with, check out:
- Issues labeled as ["good first issue"](https://github.com/remysaissy/lorm/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
- Issues labeled as ["Easy"](https://github.com/remysaissy/lorm/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy).
Additionally, it's always good to work on improving/adding examples and documentation.
## Development Setup
### Prerequisites
- Rust 1.75 or later (Edition 2024)
- SQLite (for running tests)
- cargo-expand (optional, for inspecting generated code): `cargo install cargo-expand`
- act (optional, for running CI tests locally): `brew install act` (macOS) or see [act installation](https://github.com/nektos/act)
- Docker (required if using act)
### Building the Project
```bash
# Clone the repository
git clone https://github.com/remysaissy/lorm.git
cd lorm
# Build all workspace members
cargo build
# Run tests
cargo test
# Build documentation
cargo doc --open
```
### Running Examples
```bash
# Run a specific example
cargo run --example basic_crud
# List all examples
ls examples/
```
### Testing Changes
Lorm has tests in the `lorm/tests` directory that cover various features:
```bash
# Run all tests
cargo test
# Run a specific test
cargo test test_user_is_created
# Run tests with output
cargo test -- --nocapture
```
When adding new features, please add corresponding tests following the existing patterns in `lorm/tests/main.rs`.
### Running CI Tests Locally
Before committing, you can run all GitHub Actions CI tests locally using `act`:
```bash
# Install act (one-time setup)
brew install act # macOS
# or follow instructions at https://github.com/nektos/act
# Ensure Docker is running
# Then run all CI jobs
./test.sh
# Run specific jobs only
./test.sh --format # Run format check
./test.sh --check # Run clippy
./test.sh --test # Run unit tests
./test.sh --examples # Run examples
./test.sh --coverage # Run coverage check
# List all available jobs
./test.sh --list
# Run a specific job by name
./test.sh --job coverage
```
This allows you to catch CI failures before pushing, saving time and ensuring your PR is ready for review.
**Note**: Running all jobs locally can take several minutes. Consider running specific jobs during development and run all jobs before committing.
### Code Coverage
Lorm uses `cargo-llvm-cov` for code coverage reporting:
```bash
# Install cargo-llvm-cov
cargo install cargo-llvm-cov
# Generate HTML coverage report (opens in browser)
./coverage.sh
# Generate lcov report for CI
./coverage.sh --lcov
# Show coverage summary in terminal
./coverage.sh --text
# Generate all formats
./coverage.sh --all
# Check coverage meets thresholds (80% minimum)
./coverage.sh --check-thresholds
# Combine flags
./coverage.sh --clean --html --check-thresholds
```
#### Coverage Requirements
Lorm enforces minimum coverage thresholds in CI:
- **Line Coverage**: ≥ 80%
- **Region Coverage**: ≥ 80%
- **Function Coverage**: ≥ 80%
Pull requests that reduce coverage below these thresholds will fail CI. Coverage reports are automatically generated and uploaded to codecov.io. When contributing, aim to maintain or improve coverage for modified code.
### Inspecting Generated Code
To see what code Lorm generates, use `cargo-expand`:
```bash
# Install cargo-expand
cargo install cargo-expand
# Expand macros in tests
cd lorm
cargo expand --test main
```
This is helpful for:
- Understanding how the macro works
- Debugging macro issues
- Verifying generated code correctness
### Code Style
- Follow standard Rust formatting: `cargo fmt`
- Ensure code passes clippy: `cargo clippy -- -D warnings`
- Add documentation comments for public APIs
- Keep generated code clean and readable
### Documentation
When contributing:
- Update README.md if adding user-facing features
- Add rustdoc comments for public APIs
- Create examples for significant features
- Update CHANGELOG.md following [Keep a Changelog](https://keepachangelog.com/) format
## Communication
If you're unsure about your contribution or simply want to ask a question about anything, you can:
- Discuss something directly in the [Github issue](https://github.com/remysaissy/lorm/issues).
## Code of Conduct
Be respectful, constructive, and welcoming to all contributors.