Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (86 loc) · 5.85 KB

CONTRIBUTING.md

File metadata and controls

120 lines (86 loc) · 5.85 KB
Raw

Contributing to Chess_Engine_in_Rust

Thank you for your interest in contributing. This project is a browser-first, high-performance chess engine designed to be both a fast WebAssembly application and an educational codebase that explains how modern chess engines work from first principles.

To keep the codebase maintainable, fast, and educational, all contributors are expected to follow these guidelines.

Architectural Boundaries

The workspace is organized into focused crates with strict separation of concerns:

  • chess-core: The rules engine and move generator.
    • Handles bitboards, magic bitboard attack tables, legal move generation, move validation, make/unmake move, FEN parsing, and Zobrist hashing.
    • Constraint: Must remain 100% agnostic to search algorithms and evaluation heuristics. No search code belongs here.
  • chess-search: Search algorithms, evaluation functions, and engine orchestration.
    • Implements Negamax, Principal Variation Search (PVS), Alpha-Beta pruning, Quiescence search, Transposition Tables, Move Ordering (MVV-LVA, Killer/History heuristics), and the baseline evaluation functions (Core-0 and Core-1).
    • Owns EngineConfig, which acts as the central control plane for all engine heuristics and tiers.
  • chess-wasm: Browser and WebAssembly bindings.
    • Exposes the engine API across the WASM boundary to JavaScript/TypeScript and Web Workers.
    • Constraint: Must remain lean and lightweight (~100 KB pure classical WASM binary).
  • tools/replay-gen: Offline CLI tooling.
    • Parses PGN files and runs engine evaluations to generate structured JSON game records for the replay viewer.

The Central Toggle Rule

This is a foundational architectural rule for the repository:

The baseline classical system (Core-1), as it exists today, must always be reachable, exactly as it is today.

This engine is built to teach developers how chess systems work from first principles and how components connect, while leaving room for community-driven enhancements. If you contribute features that expand the project outside the classical realm—such as NNUE, neural weights, ONNX runtimes, or experimental ML backends—you must adhere to the following:

  1. Modular Feature Gating: Heavy dependencies, weights, and runtimes must be gated behind Cargo features in Cargo.toml (e.g., nnue = [], experimental = []). The default feature set must remain ["classical"] so standard builds never suffer binary bloat.
  2. Central Configuration Wire-in: All engine tiers and experimental heuristics must be configurable through chess-search/src/config.rs (EngineConfig).
  3. Graceful Fallback: The engine's resolution logic (resolve_engine()) must automatically fall back to Core-1 when an uncompiled or disabled engine tier is requested. Uncompiled additions must never panic or crash the engine.
  4. Target Portability: All core code must compile cleanly to wasm32-unknown-unknown without relying on native OS-specific libraries.

Local Development Setup

Prerequisites

  • Rust: Stable toolchain (1.75+ recommended)
  • WebAssembly Target: 
    rustup target add wasm32-unknown-unknown
  • wasm-pack (for browser WASM builds): 
    cargo install wasm-pack
  • Bun or Node.js (for running the local interactive web interface): 
    bun --version # or node -v

Building the Project

# Build all native crates
cargo build --workspace

# Build the WebAssembly package for browser use
wasm-pack build chess-wasm --target web --release

Quality Gates & Verification

Before opening a pull request, your code must pass all automated quality checks. CI runs with strict warnings-as-errors flags on all targets:

1. Code Formatting

cargo fmt --all -- --check

2. Strict Compiler Lints

cargo clippy --workspace --all-targets --all-features -- -D warnings

3. Full Test Suite

cargo test --workspace --all-features

4. WebAssembly Target Verification

Verify that chess-wasm builds cleanly for the WebAssembly target without warnings or errors:

cargo check --target wasm32-unknown-unknown -p chess-wasm --all-features

5. Gauntlet Regression Benchmark

If you modify search heuristics, move ordering, or evaluation logic in chess-search, you must run the 100-game engine gauntlet against Core-0:

cargo test -p chess-search --release --test gauntlet -- --ignored

Include your win/draw/loss record and effective NPS in your pull request description. Any change that degrades performance or search quality without strong justification will not be merged.

Pull Request Guidelines

  1. Discuss Major Changes First: For non-trivial features, architectural modifications, or refactors, open an issue first to discuss design and alignment.
  2. Keep Commits Atomic: Make focused, logically grouped commits with clear, descriptive commit messages.
  3. Document Non-Obvious Decisions: If you implement a tricky heuristic or optimization, explain the rationale in the code comments and PR notes.
  4. Preserve Educational Clarity: Favor readable, idiomatic Rust over convoluted micro-optimizations unless backed by definitive profiling benchmarks.

License Hygiene & Training Data

This project is dual-licensed under MIT OR Apache-2.0.

  • Clean-Room Standard: You must ensure that no copyrighted or copyleft (GPL) code—such as algorithms, data structures, or code lifted directly from Stockfish or other GPL engines—enters this codebase.
  • AI-Assisted Contributions: If you use AI assistants (Claude, Copilot, ChatGPT, etc.) during development, read our AI Policy. You are 100% responsible for verifying the provenance, correctness, and license compatibility of every line of code you submit.