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](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Documentation Standards](#documentation-standards)
- [Coding Standards](#coding-standards)
- [Testing Requirements](#testing-requirements)
- [Commit Guidelines](#commit-guidelines)
- [Pull Request Process](#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

```bash
# 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](./.claude/guides/local/setup.md)**

---

## Development Workflow

### 1. Create a Branch

```bash
# 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:

```bash
# 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](./.claude/guides/local/quality-checks.md)**

---

## 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](./.claude/guides/coding-guidelines.md)** 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

```rust
// 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

```bash
# 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](./.claude/guides/local/testing.md)**

### Test Standards

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

```bash
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

```markdown
## 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](./docs/README.md)**

---

## Getting Help

| Question | Resource |
|----------|----------|
| How do I... | [Documentation Index](./docs/README.md) |
| Setup issues | [Setup Guide](./.claude/guides/local/setup.md) |
| Test failures | [Testing Guide](./.claude/guides/local/testing.md) |
| Code questions | [GitHub Discussions](https://github.com/orchard9/stemedb/discussions) |
| Bug reports | [GitHub Issues](https://github.com/orchard9/stemedb/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](./README.md)**