Contributing to RustAPI

Thank you for your interest in contributing to RustAPI! We welcome contributions of all kinds - bug reports, feature requests, documentation improvements, and code contributions.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Testing
• Code Style
• Pull Request Process
• Project Structure
• Release Process
• Getting Help

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

Governance & Merge Policy

To maintain repository stability and code quality, we enforce the following policies:

1. Branch Protection: The main branch is protected. Direct pushes are disabled.
2. Pull Requests: All changes must be submitted via Pull Request.
3. Linear History: We use Squash Merges to keep the history clean and linear. Merge commits are disabled.
4. Force Pushes: Force pushes to main are strictly prohibited.

Getting Started

First Time Contributors

New to open source? Check out these resources:

• How to Contribute to Open Source
• First Contributions

Quick Start

1. Fork the repository - Click the "Fork" button on GitHub
2. Clone your fork:

   git clone https://github.com/YOUR-USERNAME/RustAPI.git
   cd RustAPI
   

3. Add upstream remote:

   git remote add upstream https://github.com/Tuntii/RustAPI.git
   

4. Create a new branch:

   git checkout -b feature/your-feature-name
   

5. Make your changes (see guidelines below)
6. Test your changes:

   cargo test --workspace
   cargo clippy --workspace -- -D warnings
   cargo fmt --all -- --check
   

7. Commit and push:

   git add .
   git commit -m "feat: add awesome feature"
   git push origin feature/your-feature-name
   

8. Create a Pull Request on GitHub

Development Setup

Prerequisites

• Rust 1.85 or later (MSRV) - Install from rustup.rs
• Git - For version control
• Code editor - VS Code with rust-analyzer recommended

Building

# Build all crates
cargo build --workspace

# Build with all features
cargo build --workspace --all-features

# Build specific crate
cargo build -p rustapi-core

# Build in release mode
cargo build --workspace --release

Running Examples

In-repo examples live under crates/rustapi-rs/examples/. Start with the golden path (see docs/GOLDEN_PATH.md):

# First run — handler → OpenAPI → probes
cargo run -p rustapi-rs --example golden_path

# List in-repo examples
ls crates/rustapi-rs/examples/

Making Changes

Finding Issues to Work On

• Look for issues labeled good first issue or help wanted
• Check the project board for planned features
• Feel free to propose new features in an issue first

Before You Start

1. Check existing issues - Someone might already be working on it
2. Discuss large changes - Open an issue to discuss your approach
3. Keep PRs focused - One feature/fix per PR

Types of Contributions

• 🐛 Bug Fixes - Fix issues and add regression tests
• ✨ New Features - Add new functionality
• 📝 Documentation - Improve docs, add examples
• 🎨 Code Quality - Refactoring, performance improvements
• ✅ Tests - Add test coverage
• 🔧 Tooling - Improve build scripts, CI/CD

Testing

Testing

Running Tests

# Run all tests
cargo test --workspace

# Run tests with all features
cargo test --workspace --all-features

# Run tests for a specific crate
cargo test -p rustapi-core

# Run a specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run property tests (may take longer)
cargo test --workspace --release

Writing Tests

• Add unit tests in the same file as the code
• Add integration tests in tests/ directory
• Use property-based testing with proptest for complex logic
• Test error cases and edge cases
• Add doc tests for public APIs

Example:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // Arrange
        let input = setup_test_data();
        
        // Act
        let result = your_function(input);
        
        // Assert
        assert_eq!(result, expected);
    }
}

Code Style

Formatting

All code must be formatted with rustfmt:

# Format all code
cargo fmt --all

# Check formatting without making changes
cargo fmt --all -- --check

Configuration is in rustfmt.toml.

Linting

All code must pass clippy checks:

# Run clippy on all crates
cargo clippy --workspace --all-features -- -D warnings

# Run clippy with specific lint levels
cargo clippy --workspace -- -W clippy::all -D warnings

Pre-commit Hooks (Recommended)

We provide committed pre-commit scripts that run the same formatting + strict clippy checks (and mdBook validation for cookbook changes) as the CI lint job.

This prevents "lint failed on main" surprises.

One-time setup

Unix / Git Bash (recommended):

cp scripts/pre-commit.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Windows (PowerShell):

Copy-Item scripts\pre-commit.ps1 .git\hooks\pre-commit.ps1

After setup, the checks will run automatically on git commit for relevant staged files.

You can also run the full local CI simulation anytime:

pwsh -File scripts/simulate_ci.ps1
# or the more thorough quality script
pwsh -File scripts/check_quality.ps1

Documentation

• Public APIs must have rustdoc comments
• Use /// for item documentation
• Use //! for module documentation
• Include code examples in doc comments
• Doc examples must compile and run

Example:

/// Handles HTTP requests using the registered routes.
///
/// # Example
///
/// ```rust
/// use rustapi_rs::prelude::*;
///
/// #[rustapi_rs::get("/hello")]
/// async fn hello() -> &'static str {
///     "Hello, World!"
/// }
/// ```
pub async fn handle_request() { }

Naming Conventions

• Use snake_case for functions, variables, modules
• Use PascalCase for types, traits, enums
• Use SCREAMING_SNAKE_CASE for constants
• Prefix private items with underscore if unused
• Use descriptive names, avoid abbreviations

Error Handling

• Use Result<T, E> for fallible operations
• Use thiserror for custom error types
• Provide helpful error messages
• Document error conditions in rustdoc
• Provide helpful error messages

API Guidelines

To ensure rustapi-rs remains stable and reliable, please follow these API design rules:

1. Visibility: Prefer pub(crate) by default. Only expose items that are intended for end-users.
2. Unsafe Code: avoid unsafe unless absolutely necessary.
   • All unsafe blocks must have a // SAFETY: ... comment explaining why it is safe.
   • Miri tests should be added for unsafe code.
3. SemVer: We strictly follow semantic versioning.
   • Breaking changes to public APIs require a MAJOR version bump.
   • Additions require a MINOR version bump.
   • Patches must be backwards compatible.

Pull Request Process

PR Title Format

Follow Conventional Commits:

• feat: add new feature - New functionality
• fix: resolve bug in router - Bug fixes
• docs: update API documentation - Documentation changes
• refactor: restructure handler logic - Code refactoring
• test: add router tests - Test additions/changes
• perf: optimize route matching - Performance improvements
• chore: update dependencies - Maintenance tasks
• ci: update GitHub Actions - CI/CD changes

PR Checklist

Before submitting, ensure:

• Code follows style guidelines (cargo fmt, cargo clippy); pre-commit hook recommended (see above)
• All tests pass (cargo test --workspace)
• New tests added for new functionality
• Documentation updated (if applicable)
• Examples added/updated (if applicable)
• CHANGELOG.md updated (for significant changes)
• No breaking changes (or clearly documented)
• PR description explains what and why

PR Template

When creating a PR, include:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #123, Closes #456

## Testing
- Describe how you tested the changes
- Include relevant test commands

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Tests pass locally
- [ ] Code is formatted
- [ ] Documentation updated

Review Process

1. Automated checks run on your PR (tests, formatting, clippy)
2. Maintainer review - May request changes
3. Address feedback - Push updates to your branch
4. Approval - Once approved, PR will be merged
5. Merge - Squash merge to main branch

After Your PR is Merged

• Your changes will be in the next release
• You'll be credited in CHANGELOG.md
• Thank you for contributing! 🎉

Commit Guidelines

• Write clear, concise commit messages
• Use present tense ("Add feature" not "Added feature")
• Use imperative mood ("Move cursor to..." not "Moves cursor to...")
• Reference issues when applicable (Fixes #123, Closes #456)
• Limit first line to 72 characters
• Add detailed description in commit body if needed

Good commit messages:

feat: add WebSocket support to core router

Implement WebSocket handler registration and upgrade logic.
Includes connection lifecycle management and message handling.

Fixes #123

fix: resolve path parameter parsing issue

Path parameters with special characters were not properly decoded.
Now using percent-decoding for all path params.

Closes #456

Project Structure

RustAPI/
├── crates/
│   ├── rustapi-rs/       # 🎯 Public-facing crate (re-exports)
│   │   └── examples/     # 📖 In-crate examples (start with golden_path)
│   ├── rustapi-core/     # ⚙️  Core HTTP engine and routing
│   ├── rustapi-macros/   # 🔧 Procedural macros (#[get], #[post], etc.)
│   ├── rustapi-validate/ # ✅ Validation integration (validator crate)
│   ├── rustapi-openapi/  # 📚 OpenAPI/Swagger documentation
│   ├── rustapi-extras/   # 🎁 Optional features (JWT, CORS, SQLx helpers)
│   ├── rustapi-toon/     # 🎨 TOON format support
│   ├── rustapi-ws/       # 🔌 WebSocket support
│   ├── rustapi-view/     # 🖼️  Template rendering (Tera)
│   ├── rustapi-testing/  # 🧪 Test client and fluent assertions
│   ├── rustapi-grpc/     # 📡 gRPC helpers (Tonic)
│   ├── rustapi-mcp/      # 🤖 Native MCP (expose routes as LLM tools)
│   └── cargo-rustapi/    # 📦 CLI tool
├── docs/                 # 📝 Documentation
└── scripts/              # 🛠️  Build and publish scripts

Crate Dependencies

rustapi-rs (public API)
├── rustapi-core (HTTP engine)
│   ├── rustapi-macros (proc macros)
│   └── rustapi-openapi (OpenAPI specs)
├── rustapi-validate (validation)
├── rustapi-extras (optional features)
├── rustapi-toon (TOON format)
├── rustapi-ws (WebSocket)
└── rustapi-view (templates)

Where to Make Changes

• Adding HTTP features → rustapi-core
• Adding proc macros → rustapi-macros
• Adding validation → rustapi-validate
• Adding OpenAPI features → rustapi-openapi
• Adding optional features → rustapi-extras
• Adding examples → crates/rustapi-rs/examples/
• Adding tests → relevant crate's tests/ directory
• Adding docs → docs/ or inline rustdoc

Release Process

Versioning

RustAPI follows Semantic Versioning driven by conventional commits (from v0.2.0). We do not use git commit count for versions.

Commit type	Bump
feat:	minor
fix:, chore:, docs:, …	patch
BREAKING CHANGE / type!:	major

Automation: release-plz (see release-plz.toml and .github/workflows/release-plz.yml). Prefer squash-merge titles that stay conventional (feat: …, fix: …).

Release Checklist (Maintainers)

Preferred (automated):

1. Keep CHANGELOG.md Unreleased section accurate as PRs land.
2. Merge work to main with conventional commit messages.
3. Merge the release-plz PR when CI is green (it bumps workspace versions).
4. release-plz tags vX.Y.Z, opens the GitHub release, and publishes to crates.io (CARGO_REGISTRY_TOKEN secret required).
5. Optionally refresh RELEASES.md for major stories.

Manual fallback:

1. Bump [workspace.package].version and path-dep versions in root Cargo.toml
2. Move Unreleased → dated section in CHANGELOG.md; update docs version pins if needed
3. cargo test --workspace (and --all-features when DB libs are available)
4. Tag vX.Y.Z, push tag, run Publish workflow or scripts/smart_publish.ps1

Documentation Contributions

Documentation is part of the public product. When you change behavior, update the matching guide:

Change type	Update
User-facing API or feature	Cookbook recipe or docs/ guide + CHANGELOG.md
Internal refactor only	CHANGELOG.md under Changed / Fixed if user-visible
New example	crates/rustapi-rs/examples/ + examples README
Contributor workflow	CONTRIBUTING.md or docs/COMMUNITY.md

Entry points for readers: docs/README.md (hub), docs/COMMUNITY.md (open source), Cookbook SUMMARY.

Run cargo doc -p rustapi-rs --all-features locally when you touch public types.

Getting Help

Resources

• 📖 Documentation: docs/ · Community guide
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📧 Contact: Open an issue for questions

Reporting Issues

When reporting bugs, please include:

1. Environment:

   • Rust version: rustc --version
   • RustAPI version
   • Operating system

2. Description:

   • What you expected to happen
   • What actually happened
   • Steps to reproduce

3. Code:

   • Minimal reproduction code
   • Relevant error messages
   • Stack traces (if applicable)

Issue Template:

## Description
Brief description of the issue

## Environment
- Rust version: 1.85.0
- RustAPI version: 0.2.0
- OS: Windows 11

## Steps to Reproduce
1. Create a route with...
2. Call the endpoint...
3. See error...

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Code
\```rust
// Minimal reproduction code
\```

## Error Messages
\```
// Error output
\```

Feature Requests

We welcome feature requests! Please:

1. Check if the feature already exists or is planned
2. Explain the use case and why it's valuable
3. Consider if it fits the project's scope
4. Be open to discussion about implementation

Security Issues

Do not open public issues for security vulnerabilities!

Please report security issues via:

• GitHub Security Advisories (preferred)
• Email to maintainers

Recognition

All contributors will be:

• Listed in CHANGELOG.md for their contributions
• Credited in release notes
• Added to GitHub's contributors list

Top Contributors

Special thanks to all our contributors! You can see them on the contributors page.

---

Thank You! 🙏

Your contributions help make RustAPI better for everyone. Whether you're fixing a typo, adding a feature, or reporting a bug - every contribution matters!

Happy coding! 🦀✨