Contributing

Welcome to the Fluree contributor documentation! This section provides everything you need to contribute to Fluree.

Getting Started

Dev Setup

Set up your development environment:

Install dependencies
Clone repository
Build from source
Run development server
IDE configuration

Tests

Testing guide:

Running tests
Writing tests
Test organization
Integration tests
Benchmarking
Continuous integration

Adding Tracing Spans

How to instrument new code paths with tracing spans:

The two-tier span strategy (info / debug / trace)
Code patterns for sync and async spans
Deferred field recording
Testing spans with SpanCaptureLayer
Common gotchas (!Send guards, OTEL floods, etc.)

W3C SPARQL Compliance Suite

Guide to the manifest-driven W3C compliance test suite:

Running and interpreting results
Debugging failures
From failure to issue/PR workflow
Using Claude Code for compliance work
Architecture overview

SHACL Implementation

How SHACL validation is wired into Fluree, for contributors adding constraints or fixing bugs:

Pipeline: compile → cache → validate
Crate layout (fluree-db-shacl / -transact / -api)
Shared post-stage helper and its call sites
Per-graph config, f:shapesSource, target-type resolution
Adding a new constraint (walkthrough)
Testing patterns (unit + integration + temp-revert regression trick)
Known gaps (sh:uniqueLang, sh:qualifiedValueShape, cross-txn cache)

How to Contribute

Ways to Contribute

Report Bugs: File issues with reproduction steps
Suggest Features: Propose enhancements with use cases
Fix Bugs: Submit pull requests for bug fixes
Add Features: Implement new capabilities
Improve Documentation: Fix typos, clarify explanations, add examples
Review Pull Requests: Help review others’ contributions
Answer Questions: Help users in discussions

Before Contributing

Check existing issues: Search for duplicate issues
Read documentation: Understand the feature area
Discuss major changes: Open issue before large PRs
Follow style guide: Match existing code style
Add tests: Include tests for new features
Update docs: Document new features

Contribution Workflow

1. Fork Repository

# Fork on GitHub, then clone
git clone https://github.com/YOUR-USERNAME/db.git
cd db

2. Create Branch

git checkout -b feature/my-feature

Branch naming:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring
test/ - Test additions

3. Make Changes

Edit code, following style guidelines.

4. Add Tests

# Run existing tests
cargo test

# Add new tests
# Edit tests/test_my_feature.rs

5. Run Checks

# Format code
cargo fmt

# Lint code
cargo clippy

# Run all tests
cargo test --all

6. Commit Changes

git add .
git commit -m "Add feature: description"

Commit message format:

Short summary (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.

- Key point 1
- Key point 2

Fixes #123

7. Push and Create PR

git push origin feature/my-feature

Create pull request on GitHub.

8. Address Review Comments

Respond to reviewer feedback, make requested changes.

Code Style

Rust Style

Follow Rust standard style:

# Format all code
cargo fmt

# Check style
cargo clippy

Naming Conventions

Types: PascalCase

#![allow(unused)]
fn main() {
struct Dataset { ... }
enum QueryResult { ... }
}

Functions: snake_case

#![allow(unused)]
fn main() {
fn execute_query() { ... }
fn parse_json_ld() { ... }
}

Constants: SCREAMING_SNAKE_CASE

#![allow(unused)]
fn main() {
const MAX_QUERY_SIZE: usize = 1_048_576;
}

Modules: snake_case

#![allow(unused)]
fn main() {
mod query_engine;
mod storage_backend;
}

Documentation

Document public APIs:

#![allow(unused)]
fn main() {
/// Executes a query against the dataset.
///
/// # Arguments
///
/// * `query` - The query to execute
/// * `context` - Execution context
///
/// # Returns
///
/// Query results or error
///
/// # Examples
///
/// ```
/// let results = dataset.query(&query, &context)?;
/// ```
pub fn query(&self, query: &Query, context: &Context) -> Result<Vec<Solution>> {
    // Implementation
}
}

Error Handling

Use Result types:

#![allow(unused)]
fn main() {
// Good
pub fn parse_query(input: &str) -> Result<Query, ParseError> {
    // ...
}

// Bad
pub fn parse_query(input: &str) -> Query {
    // No error handling
}
}

Testing

Write tests for new code:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_query_execution() {
        let query = Query::parse("...").unwrap();
        let result = execute(&query).unwrap();
        assert_eq!(result.len(), 2);
    }
}
}

Pull Request Guidelines

PR Title

Format: category: short description

Examples:

feat: Add SPARQL property paths support
fix: Correct transaction time ordering
docs: Update query examples
test: Add integration tests for time travel
refactor: Simplify index scan logic

PR Description

Include:

Summary: What does this PR do?
Motivation: Why is this needed?
Changes: What changed?
Testing: How was it tested?
Breaking Changes: Any breaking changes?

Example:

## Summary
Adds support for SPARQL property paths, enabling recursive graph traversal.

## Motivation
Many users need to query hierarchical data structures. Property paths are a standard SPARQL feature.

## Changes
- Added property path parser to fluree-db-sparql
- Implemented path evaluation in query engine
- Added tests for various path patterns

## Testing
- Unit tests for parser
- Integration tests for path queries
- Benchmarks show acceptable performance

## Breaking Changes
None