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

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

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

A Fixes #123 trailer closes the issue once the commit reaches the default branch, but it does not create the linked pull request relationship — so put the closing keyword in the PR body as well (or instead). See Linking issues from PRs for the three reference forms and how they behave on stacked PRs.

7. Push and Create PR

git push origin feature/my-feature

Create pull request on GitHub. Put Fixes #N / Follow-up: #N / Partially addresses #N in the PR body so the reference direction is explicit — see Linking issues from PRs.

# 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