Contributing

Thank you for your interest in contributing to Sipha! This document provides guidelines and instructions for contributing.

Code of Conduct

This project adheres to the Rust Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

Rust toolchain (stable, beta, or nightly)
cargo (comes with Rust)
rustfmt and clippy (install with rustup component add rustfmt clippy)

Development Setup

Fork the repository and clone your fork:

git clone https://github.com/yourusername/sipha.git
cd sipha

Build the project:
```
cargo build
```
Run the test suite:
```
cargo test
```

Run clippy:

cargo clippy --all-targets --all-features --workspace -- -W clippy::pedantic -W clippy::nursery -W clippy::cargo -D warnings

Check formatting:
```
cargo fmt --all -- --check
```

Development Workflow

Create a branch for your changes:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Make your changes following the coding standards below.
Write or update tests for your changes.
Ensure all tests pass:
```
cargo test --all-features
```

Run clippy and fix any warnings:

cargo clippy --all-targets --all-features --workspace -- -W clippy::pedantic -W clippy::nursery -W clippy::cargo -D warnings

Format your code:
```
cargo fmt --all
```

Commit your changes with a clear, descriptive commit message:

git commit -m "Add feature: description of what you added"

Push to your fork:

git push origin feature/your-feature-name

Open a Pull Request on GitHub with a clear description of your changes.

Coding Standards

Code Style

Follow Rust’s standard formatting conventions. Run cargo fmt before committing.
Use cargo clippy to catch common issues and follow Rust best practices.
We use pedantic clippy lints - some are allowed in clippy.toml and lib.rs, but try to follow them when possible.

Documentation

Document all public APIs with doc comments.
Include examples in doc comments where helpful.
Update the README if you add new features or change existing behavior.

Testing

Write tests for new features and bug fixes.
Aim for good test coverage, especially for critical paths.
Include both unit tests and integration tests where appropriate.
Test with different feature combinations when applicable.

Error Handling

Prefer Result types over panicking in library code.
Provide clear, actionable error messages.
Use appropriate error types from the error module.

Commit Messages

Use clear, descriptive commit messages.
Start with a verb in imperative mood (e.g., “Add”, “Fix”, “Update”).
Reference issue numbers when applicable (e.g., “Fix #123: description”).

Example:

Add incremental parsing cache invalidation

Implements cache invalidation for incremental parsing when text edits
occur. This improves performance by only re-parsing affected regions.

Fixes #42

Pull Request Process

Ensure your PR is up to date with the target branch (usually trunk).
Write a clear description of what your PR does and why.
Reference related issues if applicable.
Ensure CI passes - all tests, clippy checks, and formatting checks must pass.
Request review from maintainers.
Address feedback promptly and update your PR as needed.

Feature Requests

If you have an idea for a new feature:

Check existing issues to see if it’s already been discussed.
Open an issue describing the feature, its use case, and potential implementation approach.
Wait for maintainer feedback before implementing.

Bug Reports

When reporting bugs, please include:

A clear description of the bug
Steps to reproduce
Expected behavior
Actual behavior
Your environment (Rust version, OS, etc.)
Minimal code example if possible

Fuzz Testing

Sipha includes fuzz testing infrastructure to ensure robustness and correctness. Fuzz tests help find edge cases and potential panics in the parser.

Prerequisites

Install cargo-fuzz:

cargo install cargo-fuzz

Running Fuzz Tests

Navigate to the fuzz directory and run the fuzz targets:

cd fuzz
cargo fuzz run parser_fuzz
cargo fuzz run incremental_fuzz

Fuzz Targets

parser_fuzz: Tests the parser with random byte streams to ensure no panics occur.
incremental_fuzz: Differential fuzzing that compares incremental parsing results with full re-parsing to ensure correctness.

Adding New Fuzz Targets

To add a new fuzz target:

Create a new file in fuzz/fuzz_targets/ with your fuzz target code
Add a [[bin]] entry in fuzz/Cargo.toml pointing to your target
Run cargo fuzz list to verify the target is registered

Questions?

Feel free to open an issue for questions or discussions. We’re happy to help!

License

By contributing to Sipha, you agree that your contributions will be licensed under the MIT License.

Keyboard shortcuts

The Sipha Book