# 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 ``` ():