Skip to content

README.md

Latest commit

 

History

History
372 lines (275 loc) · 7.8 KB

README.md

File metadata and controls

372 lines (275 loc) · 7.8 KB
Raw

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

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

Before Contributing

  1. Check existing issues: Search for duplicate issues
  2. Read documentation: Understand the feature area
  3. Discuss major changes: Open issue before large PRs
  4. Follow style guide: Match existing code style
  5. Add tests: Include tests for new features
  6. 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

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.

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

struct Dataset { ... }
enum QueryResult { ... }

Functions: snake_case

fn execute_query() { ... }
fn parse_json_ld() { ... }

Constants: SCREAMING_SNAKE_CASE

const MAX_QUERY_SIZE: usize = 1_048_576;

Modules: snake_case

mod query_engine;
mod storage_backend;

Documentation

Document public APIs:

/// 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:

// 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:

#[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:

  1. Summary: What does this PR do?
  2. Motivation: Why is this needed?
  3. Changes: What changed?
  4. Testing: How was it tested?
  5. 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

PR Checklist

  • Code follows style guidelines
  • Tests added/updated
  • Documentation updated
  • All tests pass
  • No clippy warnings
  • Commit messages clear
  • PR description complete

Review Process

What Reviewers Look For

  1. Correctness: Does it work as intended?
  2. Tests: Adequate test coverage?
  3. Style: Follows conventions?
  4. Documentation: Properly documented?
  5. Performance: No obvious performance issues?
  6. Breaking Changes: Backward compatible?

Responding to Reviews

  • Be receptive to feedback
  • Ask questions if unclear
  • Make requested changes promptly
  • Explain your reasoning when appropriate
  • Say thanks for helpful reviews

Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Assume good intentions
  • Give constructive feedback
  • Welcome newcomers
  • No harassment or discrimination

Communication

  • GitHub Issues: Bug reports, feature requests
  • Pull Requests: Code contributions
  • Discussions: Questions, ideas, help

Getting Help

  • Read documentation first
  • Search existing issues
  • Ask specific questions
  • Provide reproduction steps
  • Be patient and respectful

License

Fluree DB is distributed under the Business Source License 1.1, which converts to Apache License 2.0 on each version's Change Date.

By contributing, you license your contributions to Fluree, PBC under the Apache License 2.0, and agree that Fluree may distribute them as part of Fluree DB under the Business Source License, the Apache License 2.0, and Fluree's commercial licenses.

Recognition

Contributors are recognized in:

  • CONTRIBUTORS.md file
  • Release notes
  • GitHub contributors page

Thank you for contributing to Fluree!

Related Documentation