notion-sql/docs/RUST-BEST-PRACTICES.md

Rust Project Best Practices

Test Organization

❌ Don't Mix Tests with Source Code

// src/notion.rs - BAD
fn some_function() { ... }

#[cfg(test)]
mod tests {
    #[test]
    fn test_something() { ... }
}

✅ Do Use Separate Test Directory

src/
  notion.rs          # Only implementation code
tests/
  notion.rs          # Unit tests for notion module
  integration.rs     # Integration tests

Project Structure

notion-sql/
├── src/
│   ├── main.rs      # Binary entrypoint
│   └── lib.rs       # Library exports
├── tests/           # All tests (unit + integration)
│   ├── cli.rs       # CLI module tests
│   ├── filter.rs    # Filter module tests
│   └── integration.rs  # Integration tests
├── examples/        # Example usage
│   ├── README.md
│   └── select_basic.md
├── docs/            # Project documentation
└── .github/workflows/
    ├── ci.yml       # CI pipeline
    └── release.yml  # Release automation

Code Quality Gates

Always Pass

cargo fmt --check          # Formatting
cargo clippy --all-targets --all-features -- -D warnings  # Lints
cargo test --all-targets   # All tests (39 tests passing)

Build Verification

cargo build --release      # Release build
cargo doc --no-deps        # Documentation generation

CI/CD Pipeline

CI Workflow (ci.yml)

• Runs on PRs and pushes to main branches
• Tests: Rust checks, clippy, formatting, tests, release build
• Uploads branch artifacts for develop/release branches

Release Workflow (release.yml)

• Triggered by version tags (vX.Y.Z)
• Builds all configured targets
• Creates GitHub release with assets
• Publishes Homebrew formula

Target Platforms

Configure all platforms in Cargo.toml:

[workspace.metadata.dist]
targets = [
  "aarch64-apple-darwin",      # macOS ARM (Apple Silicon)
  "x86_64-apple-darwin",       # macOS Intel
  "aarch64-unknown-linux-gnu", # Linux ARM
  "x86_64-unknown-linux-gnu",  # Linux x86
  "x86_64-pc-windows-msvc"     # Windows x86
]

Release Checklist

Before tagging:

• All tests pass (cargo test --all-targets)
• Clippy clean (cargo clippy --all-targets)
• Formatting correct (cargo fmt --check)
• CHANGELOG.md updated
• Version bumped in Cargo.toml

After tagging:

• Release workflow completes successfully
• All 5 platform binaries built
• Homebrew formula published
• GitHub release created with all assets

Branch Protection

Enable branch protection for main:

• Require pull request reviews (1 approval)
• Enforce admin restrictions
• Disable force pushes
• Disable deletions

Repository ruleset for tags:

• Protect tags matching v*
• Prevent tag deletions
• Prevent force pushes

Common Mistakes

1. Mixing tests with source - Use separate tests/ directory
2. Missing Windows target - Always include x86_64-pc-windows-msvc
3. Unverified Homebrew token - Ensure HOMEBREW_TAP_TOKEN secret exists
4. Draft releases left open - Always publish releases after workflow completes