stemedb/CONTRIBUTING.md

Contributing to Episteme

Thank you for your interest in contributing to Episteme (StemeDB)! This document provides guidelines for contributing code, documentation, and ideas to the project.

---

Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Documentation Standards
• Coding Standards
• Testing Requirements
• Commit Guidelines
• Pull Request Process

---

Code of Conduct

ZERO TOLERANCE FOR MEDIOCRITY: We build enterprise-grade products that must survive in production. Panics are UNACCEPTABLE. Broken pipe errors are UNACCEPTABLE. Sloppy testing is UNACCEPTABLE. Every line of code ships to paying customers who depend on it.

Principles:

• Test everything
• Handle every error
• No shortcuts
• No excuses
• Leave code better than you found it

---

Getting Started

Prerequisites

• Rust 1.75+ (rustup update stable)
• Git
• Basic understanding of knowledge graphs and conflict resolution

Initial Setup

# Clone repository
git clone https://github.com/orchard9/stemedb.git
cd stemedb

# Build workspace
cargo build --workspace

# Run tests
cargo test --workspace

# Verify quality checks pass
cargo clippy --workspace -- -D warnings
cargo fmt --check

→ Full Setup Guide

---

Development Workflow

1. Create a Branch

# Feature branch
git checkout -b feature/your-feature-name

# Bug fix branch
git checkout -b fix/issue-description

# Documentation branch
git checkout -b docs/what-youre-documenting

2. Make Changes

• Write clean, readable code
• Add tests for new functionality
• Update documentation as needed
• Run quality checks locally before committing

3. Pre-Commit Checks

Before committing, ensure all checks pass:

# Format code
cargo fmt

# Check for warnings
cargo clippy --workspace -- -D warnings

# Run tests
cargo test --workspace

# Build entire workspace
cargo build --workspace

→ Quality Checks Guide

---

Documentation Standards

File Organization

Location	Content	When to Use
Top level	Core docs only (README, quickstart, architecture, vision, roadmap)	Essential project docs
docs/	All other documentation	Everything else
docs/about/	Audience-specific overviews (investors, public, technical)	Marketing and positioning
docs/guides/	How-to guides and tutorials	Step-by-step instructions
docs/specs/	Specifications and RFCs	Technical specifications
docs/sdk/	SDK and integration guides	Client library docs
docs/research/	Research and design documents	Exploration and analysis
.claude/guides/	Developer guides	Coding standards, setup, testing

Documentation Standards

1. Directory Indexes: Every directory with 3+ markdown files needs a README.md index
2. Guide Structure: All guides must have:
   • Prerequisites section
   • What You'll Learn section
   • See Also section with related docs
3. Internal Links: Use relative paths (e.g., ./quickstart.md, not absolute URLs)
4. Top-Level Limit: Keep top-level directory to <20 files
5. Code Examples: Include runnable code snippets where possible

Writing Style

• Clear and concise: Technical but accessible
• Active voice: "Run the server" not "The server should be run"
• Present tense: "The lens resolves conflicts" not "The lens will resolve"
• Specific examples: Show concrete examples, not abstract descriptions

---

Coding Standards

Rust Guidelines

See Coding Guidelines for complete standards.

Critical Rules:

1. No Unwrap: NEVER use unwrap() or expect() in production code

   • CI enforces via clippy::unwrap_used and clippy::expect_used at deny level
   • Use ? operator or explicit match for error handling

2. Append-Only: NEVER mutate existing Assertions

   • Create new assertions instead of modifying
   • Content-addressed: Assertion ID = BLAKE3 hash of content

3. Structured Logging: Use tracing (info!, warn!, error!)

   • Clippy enforces via print_stdout/print_stderr at warn level
   • CLI binaries may use #![allow()] for user-facing output

4. Defensive Writes: All writes go through WAL with fsync

   • Storage operations must be durable
   • Test crash recovery scenarios

5. Zero-Copy Serialization: Use stemedb_core::serde::{serialize, deserialize}

   • NEVER use raw AllocSerializer in production code
   • Prefer rkyv for serialization

Code Organization

// Good: Clear module structure
mod types;
mod storage;
mod query;

// Good: Explicit error handling
fn process() -> Result<(), Error> {
    let data = fetch_data()?;
    validate(data)?;
    Ok(())
}

// Bad: Unwrap in production
fn process() {
    let data = fetch_data().unwrap();  // ❌ NEVER DO THIS
}

---

Testing Requirements

Test Coverage

• Unit tests: All public functions and methods
• Integration tests: Critical user workflows
• Property tests: Complex algorithms and data structures
• Chaos tests: Failure scenarios and recovery

Running Tests

# Fast: Single crate
cargo test -p stemedb-core

# Medium: All unit tests
cargo test --workspace --lib

# Full: Parallel runner
cargo nextest run

# Legacy: Sequential
cargo test --workspace

→ Testing Guide

Test Standards

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

    #[test]
    fn descriptive_test_name() {
        // Arrange
        let input = create_test_data();

        // Act
        let result = function_under_test(input);

        // Assert
        assert_eq!(result, expected);
    }

    #[test]
    fn handles_error_case() {
        let result = function_with_bad_input();
        assert!(result.is_err());
    }
}

---

Commit Guidelines

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(lens): add TrustAwareAuthorityLens

Implements lens that weights assertions by agent TrustRank.
- Higher TrustRank agents get more weight
- Reputation updates based on vote outcomes
- Tested with concurrent agent simulation

Closes #123

fix(wal): prevent data loss on crash during fsync

Changed fsync error handling to retry on EINTR instead
of returning error. Prevents data loss when process
receives signal during write.

Fixes #456

docs(quickstart): update cluster setup instructions

Added steps for multi-node cluster deployment and
fixed broken links to API reference.

Commit Signing

Commits should be signed with GPG:

git config --global commit.gpgsign true
git config --global user.signingkey YOUR_GPG_KEY

---

Pull Request Process

Before Submitting

1. Tests pass: All tests must pass locally
2. Clippy clean: No warnings from clippy
3. Formatted: Code formatted with cargo fmt
4. Documented: Public APIs have doc comments
5. Changelog: Update CHANGELOG.md if applicable

PR Description Template

## Summary
Brief description of changes

## Motivation
Why are these changes needed?

## Changes
- Bullet list of specific changes
- Include file paths for major changes

## Testing
How was this tested?
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing

## Checklist
- [ ] Tests pass (`cargo test --workspace`)
- [ ] Clippy passes (`cargo clippy --workspace -- -D warnings`)
- [ ] Code formatted (`cargo fmt`)
- [ ] Documentation updated
- [ ] CHANGELOG.md updated (if applicable)

Review Process

1. Automated Checks: CI runs tests and lints
2. Code Review: At least one maintainer must approve
3. Testing: Reviewer may run code locally
4. Merge: Squash and merge to main

---

Project Structure

stemedb/
├── README.md                   # Public entry point
├── CONTRIBUTING.md             # This file
├── quickstart.md               # 5-minute setup
├── architecture.md             # System design
├── vision.md                   # Product philosophy
├── roadmap.md                  # Current and planned work
│
├── crates/                     # Rust workspace
│   ├── stemedb-core/          # Core types
│   ├── stemedb-wal/           # Write-ahead log
│   ├── stemedb-storage/       # KV store
│   ├── stemedb-ingest/        # Ingestion pipeline
│   ├── stemedb-query/         # Query engine
│   ├── stemedb-lens/          # Conflict resolution
│   └── stemedb-api/           # HTTP API
│
├── applications/              # Applications built on Episteme
│   ├── aphoria/              # Code-level truth linter
│   ├── stemedb-dashboard/    # Admin dashboard
│   └── disputed/             # Controversy explorer
│
├── sdk/                       # Client libraries
│   └── go/                   # Go SDK
│
├── docs/                      # Documentation
│   ├── README.md             # Documentation hub
│   ├── about/                # Audience-specific docs
│   ├── guides/               # How-to guides
│   ├── specs/                # Specifications
│   ├── sdk/                  # SDK documentation
│   └── research/             # Research documents
│
└── .claude/                   # AI agent guides
    ├── guides/               # Developer guides
    ├── skills/               # Claude Code skills
    └── agents/               # Specialized agents

→ Full Repo Structure

---

Getting Help

Question	Resource
How do I...	Documentation Index
Setup issues	Setup Guide
Test failures	Testing Guide
Code questions	GitHub Discussions
Bug reports	GitHub Issues

---

Recognition

Contributors are recognized in:

• Git commit history
• Release notes
• Project README (for significant contributions)

---

License

By contributing to Episteme, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for contributing to Episteme!

← Back to README