# Contributing to Sable
Thank you for your interest in contributing to Sable! This document provides guidelines and information for contributors.
## Project Structure
Sable is organized as a Cargo workspace with multiple crates:
```
sable/
├── Cargo.toml # Workspace root
├── src/lib.rs # Main sable crate (re-exports)
├── crates/
│ └── sable-core/ # Math, handles, colors, time utilities
│ └── src/
│ ├── lib.rs
│ ├── math/ # Vec2, Vec3, Vec4, Mat3, Mat4, Quat
│ ├── handle.rs # Generational indices
│ ├── color.rs # Srgba, LinearRgba
│ └── time.rs # Time tracking, Stopwatch
├── .cargo-husky/hooks/ # Git hook scripts
└── .cursor/rules/ # Development guidelines
```
## Development Setup
### Prerequisites
- **Rust 2024 edition** — Use `rustup update` to get the latest toolchain
- **Vulkan SDK** — Required for GPU development (install from [LunarG](https://vulkan.lunarg.com/))
- **Git** — Version control
### Clone and Build
```bash
git clone https://github.com/PegasusHeavyIndustries/sable.git
cd sable
# Install development tools
cargo install cargo-commitlint
# Build the workspace
cargo build --workspace
# Run all tests (also installs git hooks via cargo-husky)
cargo test --workspace
```
### Useful Commands
```bash
# Run tests for a specific crate
cargo test -p sable-core
# Run clippy on the entire workspace
cargo clippy --workspace -- -D warnings
# Format all code
cargo fmt --all
# Build documentation
cargo doc --workspace --no-deps --open
# Check a specific crate
cargo check -p sable-core
```
## Git Hooks
This project uses cargo-husky with custom hooks. All hooks are installed automatically when you run `cargo test`.
| `pre-commit` | Fast checks before each commit | `cargo fmt --check`, `cargo clippy` |
| `commit-msg` | Validate conventional commit format | `cargo commitlint check` |
| `pre-push` | Full validation before pushing | `cargo test`, `cargo clippy`, `cargo doc` |
The hooks are defined in `.cargo-husky/hooks/` and copied to `.git/hooks/` by cargo-husky.
### Hook Details
**pre-commit** (runs on every commit):
- Checks code formatting with `cargo fmt --check`
- Runs `cargo clippy --all-targets --all-features -- -D warnings`
- Fast feedback loop for local development
**commit-msg** (runs on every commit):
- Validates commit message follows [Conventional Commits](https://www.conventionalcommits.org/)
- Uses `cargo-commitlint` for validation
- Shows helpful error messages with expected format
**pre-push** (runs before pushing):
- Runs full test suite with `cargo test --all-features`
- Runs clippy one more time
- Checks documentation builds without errors
- Ensures code quality before sharing with team
## Commit Messages
We follow [Conventional Commits](https://www.conventionalcommits.org/). All commit messages are validated automatically.
### Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
### Types
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no code change |
| `refactor` | Code restructuring |
| `perf` | Performance improvement |
| `test` | Adding or fixing tests |
| `build` | Build system or dependencies |
| `ci` | CI/CD changes |
| `chore` | Maintenance |
| `revert` | Reverting a commit |
### Scopes
Use the crate name without `sable-` prefix:
- `core`, `platform`, `gpu`, `metal`, `dx12`, `render`, `assets`, `scene`
- `audio`, `physics`, `puppet`, `script`, `editor`, `macros`, `app`
- `examples`, `deps`, `*` (multiple crates)
### Examples
```bash
# Feature
git commit -m "feat(render): add cascaded shadow maps"
# Bug fix
git commit -m "fix(gpu): prevent buffer overflow in allocator"
# Breaking change
git commit -m "feat(scene)!: use quaternions for rotation"
# With body
git commit -m "perf(render): batch draw calls" -m "" -m "Reduces draw calls by 60% in typical scenes."
```
## Branching
We use git-flow. See `.cursor/rules/git-flow.mdc` for details.
- `main` - Production releases
- `develop` - Integration branch
- `feature/*` - New features
- `bugfix/*` - Bug fixes
- `release/*` - Release preparation
- `hotfix/*` - Critical fixes
## Code Style
### General Guidelines
- Run `cargo fmt` before committing
- Run `cargo clippy` and fix all warnings
- Follow Rust 2024 idioms (see `.cursor/rules/rust.mdc`)
- Write documentation for public APIs
- Include unit tests for new functionality
### Testing Requirements
- Aim for ~90% test coverage on core functionality
- Use `#[test]` for unit tests within the module
- Name tests descriptively: `test_<function>_<scenario>`
- Test edge cases (zero vectors, identity matrices, etc.)
### Documentation
- Add `//!` module-level docs to each file
- Document all public items with `///`
- Include examples in doc comments where helpful
- Run `cargo doc` to verify documentation builds
## Adding a New Crate
1. Create the crate directory:
```bash
mkdir -p crates/sable-<name>/src
```
2. Add `Cargo.toml` using workspace inheritance:
```toml
[package]
name = "sable-<name>"
version.workspace = true
edition.workspace = true
license.workspace = true
```
3. Add to workspace `Cargo.toml`:
```toml
[workspace]
members = [
"crates/sable-core",
"crates/sable-<name>", # Add here
]
```
4. Create `src/lib.rs` with module documentation
## Pull Requests
1. Create a feature branch from `develop`
```bash
git checkout develop
git pull origin develop
git checkout -b feature/my-feature
```
2. Make your changes with conventional commits
3. Ensure CI passes:
```bash
cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspace
```
4. Open PR to `develop`
5. Get review and address feedback
6. Merge with `--no-ff`
## Getting Help
- Check existing issues and discussions
- Read the `.cursor/rules/` for coding guidelines
- Look at existing code for patterns and conventions
- Ask questions in PR comments or issues
## License
By contributing to Sable, you agree that your contributions will be licensed under the same proprietary license as the project (see [LICENSE](LICENSE)). You retain copyright to your contributions but grant Pegasus Heavy Industries LLC a perpetual, irrevocable license to use, modify, and distribute your contributions as part of the Software.