diff --git a/.claude/guides/backend/rust-guidelines.md b/.claude/guides/backend/rust-guidelines.md index d808658..8b199d3 100644 --- a/.claude/guides/backend/rust-guidelines.md +++ b/.claude/guides/backend/rust-guidelines.md @@ -4,7 +4,7 @@ ## Framework -All code MUST follow patterns in [CODING_GUIDELINES.md](../../../CODING_GUIDELINES.md). +All code MUST follow patterns in [Coding Guidelines](../coding-guidelines.md). ## Core Principles diff --git a/CODING_GUIDELINES.md b/.claude/guides/coding-guidelines.md similarity index 100% rename from CODING_GUIDELINES.md rename to .claude/guides/coding-guidelines.md diff --git a/.claude/guides/local/setup.md b/.claude/guides/local/setup.md index 9c79a4e..a46bc0a 100644 --- a/.claude/guides/local/setup.md +++ b/.claude/guides/local/setup.md @@ -51,7 +51,7 @@ Settings (`.vscode/settings.json`): ``` stemedb/ CLAUDE.md # AI router (start here) - CODING_GUIDELINES.md # Rust standards + .claude/guides/coding-guidelines.md # Rust standards Cargo.toml # Workspace root crates/ stemedb-core/ # Core types and storage diff --git a/CLAUDE.md b/CLAUDE.md index f5a519c..f05f898 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ A probabilistic knowledge graph database that stores Claims, not Facts. Append-o | **Run tests** | [.claude/guides/local/testing.md](.claude/guides/local/testing.md) | | **Understand quality checks** | [.claude/guides/local/quality-checks.md](.claude/guides/local/quality-checks.md) | | **Learn about simulation** | [ai-lookup/features/simulation.md](ai-lookup/features/simulation.md) | -| **Advance the simulator** | [arena-roadmap.md](./arena-roadmap.md) | +| **Advance the simulator** | [roadmap.md#arena-simulation-roadmap](./roadmap.md#arena-simulation-roadmap) | | **Work on storage/DAG** | Load skill: `stemedb-core` | | **Implement a Lens** | Load skill: `stemedb-lens` | | **Work on domain ontology** | `crates/stemedb-ontology/` | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3f952dc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,431 @@ +# 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 + +``` +(): + + + +