Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (71 loc) · 3.57 KB

CONTRIBUTING.md

File metadata and controls

94 lines (71 loc) · 3.57 KB
Raw

Contributing to evm-fork-cache

Thanks for your interest in contributing! This crate is pre-1.0 and developed against a phased roadmap. Contributions — bug reports, tests, docs, examples, and code — are welcome.

Getting started

git clone https://github.com/KaiCode2/evm-fork-cache
cd evm-fork-cache
cargo test

The crate is a standalone workspace (it has its own Cargo.lock) and needs no network for the default test suite: every integration test builds the cache over a mocked provider. A handful of examples and benchmarks fork live mainnet state behind an RPC_URL environment variable and are skipped when it is unset.

The green bar

CI runs the checks below, and every commit on a feature branch is expected to pass all of them. Run them locally before pushing:

cargo fmt --all --check
cargo clippy --all-targets --no-deps -- -D warnings
cargo test
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

A convenience one-liner:

cargo fmt --all --check && \
cargo clippy --all-targets --no-deps -- -D warnings && \
cargo test && \
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

MSRV

The minimum supported Rust version is 1.88 (edition 2024), enforced by a dedicated CI job (cargo check --lib --locked on 1.88). Do not use std APIs newer than 1.88 in the library. Dev-only code (examples, benches, tests) is not MSRV-constrained.

Crate boundary

Keep this crate focused on the generic EVM simulation engine: cache mechanics, snapshots/overlays, freshness, access lists, revert decoding, ERC-20 helpers, multicall, deployment, and event-pipeline primitives. Protocol-specific storage layouts, AMM state, and DeFi adapters belong in evm-amm-state or downstream applications.

Tests, benchmarks, and examples

  • Tests live in tests/ (integration) and inline #[cfg(test)] modules (unit). Shared offline helpers are in tests/common/. Keep tests deterministic and network-free; use the stub StorageBatchFetchFn helpers for the freshness paths. A test should pin a behavior, not merely exercise a code path.
  • Benchmarks use Criterion and live in benches/. Offline benches must stay reproducible; RPC-gated benches must return early (skip, not fail) when RPC_URL is unset, so cargo bench is offline by default.
  • Examples live in examples/. Offline examples share examples/support/mock.rs. Each example should explain what it shows and why it matters, and be listed in the README table with its network requirement and level.

Documentation

  • Document every public item. There is no missing_docs gate, but cargo doc runs with -D warnings, so broken intra-doc links and malformed doc comments fail CI.
  • Functions returning Result should carry an # Errors section; functions that can panic should carry a # Panics section.
  • Prefer runnable doctests; mark network-dependent snippets no_run or ignore.

Commits and branches

  • Branch from main (or the active phase branch). Feature/phase branches follow the phase-N-<topic> convention.
  • Write focused commits with a clear subject line and a body explaining the why.
  • Update CHANGELOG.md under [Unreleased] for any user-visible change.

Reporting issues

Please include the crate version, Rust version, feature flags, and a minimal reproduction. Known limitations are tracked in docs/KNOWN_ISSUES.md — check there first.

License

By contributing, you agree that your contributions will be dual-licensed under the MIT and Apache-2.0 licenses, as described in the README.