# Contributing
Thanks for your interest in contributing! This guide explains how to set up your environment, make changes, run checks locally, and submit high‑quality pull requests that pass CI.
---
## Project Overview
`event-scanner` is a Rust library for monitoring and streaming EVM-based smart contract events. It is built on the `alloy` ecosystem and provides in-memory scanning. See `README.md` for features, usage, examples, and testing notes.
- Workspace manifest: `Cargo.toml`
- Library code: `src/`
- Examples: `examples/simple_counter`, `examples/historical_scanning`
- Integration tests: `tests/`
- Formatting: `rustfmt.toml`
- Toolchain pin: `rust-toolchain.toml`
- CI: `.github/workflows/check.yml` and `.github/workflows/test.yml`
---
## Prerequisites
- Rust toolchains via `rustup`
- Minimum supported Rust version (MSRV): 1.89 (see `rust-toolchain.toml`)
- Formatting uses nightly `rustfmt` in CI
- Recommended tooling
- `cargo-nextest` for fast, reliable test runs: `cargo install cargo-nextest`
- `typos` for spell checking: `cargo install typos-cli` (or `brew install typos`)
- A recent `rust-analyzer` for IDE support
- Runtime/dev tools
- For examples and some tests, you’ll need an Ethereum dev node such as Foundry’s `anvil`
---
## Repository Layout
- `src/` – core library
- `examples/` – runnable examples that deploy a demo contract and scan events
- `tests/` – integration tests covering live, historical and hybrid flows
- `.github/workflows/` – CI configuration (build, fmt, clippy, typos, tests)
---
## Getting Started
1. Fork the repository and clone your fork.
2. Ensure toolchains are installed:
- `rustup toolchain install 1.89` (MSRV)
- `rustup toolchain install nightly` (for rustfmt parity with CI)
3. Optional helpers:
- `cargo install cargo-nextest`
- `cargo install typos-cli`
Build the workspace:
```bash
cargo build --locked --all-targets --all-features
```
Run the test suite (we recommend nextest):
```bash
cargo nextest run --features test-utils
# or
cargo test --features test-utils
```
Run examples:
```bash
RUST_LOG=info cargo run -p simple_counter
# or
RUST_LOG=info cargo run -p historical_scanning
```
Note: Examples start a local `anvil` instance and deploy a demo contract.
---
## Code Style & Linting
- Formatting is enforced by `rustfmt` with the settings in `rustfmt.toml`.
- CI runs formatting on nightly. To match CI locally:
```bash
cargo +nightly fmt --all --check
```
- To apply formatting locally:
```bash
cargo +nightly fmt --all
```
- Linting is enforced with `clippy` and pedantic lints are denied.
- To check locally (matches CI):
```bash
cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic
```
- To apply automatic fixes where possible:
```bash
cargo clippy --all-targets --all-features --fix --allow-dirty --allow-staged -- -D warnings -D clippy::pedantic
```
- Spelling/typos:
- CI uses `typos`. Locally:
```bash
typos
```
---
## Local CI Parity Checklist
Before opening a PR, please ensure the following commands succeed locally:
```bash
# Build (all targets & features)
cargo build --locked --all-targets --all-features
# Format (nightly to match CI)
cargo +nightly fmt --all --check
# Lint (deny warnings, pedantic)
cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic
# Spelling
typos
# Tests (prefer nextest)
cargo nextest run --features test-utils
```
---
## Branching, Commits, and PRs
- Branch from `main` with a descriptive name, e.g. `feat/reorg-handling`, `fix/rpc-retries`, `docs/contributing`.
- Keep PRs focused and reasonably small; large changes are harder to review.
- Write clear commit messages that explain the why and the what. Conventional Commits are welcome but not required.
- Include tests for new functionality or bug fixes where applicable.
- Update documentation and examples as needed.
- Ensure CI passes. Required checks include:
- Build: cargo build
- Format: rustfmt (nightly)
- Lint: clippy (pedantic, warnings denied)
- Typos: typos
- Tests: see `.github/workflows/test.yml`
- CODEOWNERS: reviewers may be auto-assigned based on `CODEOWNERS`.
PR description template (suggested):
```markdown
## Summary
Short summary of the change and context.
## Motivation
Why is this change needed?
## Approach
Key implementation details, trade-offs, and alternatives considered.
## Checklist
- [ ] Builds locally with `--all-targets --all-features`
- [ ] `cargo +nightly fmt --all --check`
- [ ] `cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic`
- [ ] `typos`
- [ ] Tests pass (`cargo nextest run --features test-utils`)
- [ ] Docs/README/examples updated (if applicable)
```
---
## Testing Notes
- Integration tests live under `tests/` and cover live, historical, and hybrid flows.
- Prefer `cargo-nextest` for speed and improved output.
- Where practical, add regression tests when fixing bugs.
---
## Design & Architecture
- High-level architecture and core traits/components are described in `README.md`.
- For non-trivial changes (new abstractions, public API changes), please open an issue first to discuss design direction before implementation.
---
## Filing Issues
- Use GitHub Issues for bug reports and feature requests.
- Include reproduction steps, expected vs actual behavior, logs, and environment details.
- Security-related reports: please follow `SECURITY.md`.
---
## Release & Versioning
- Public crates follow semver. Breaking changes to the public API should be noted clearly in PRs and release notes.
- New features and fixes may be released in pre-releases before a stable cut.
---
## Community Standards
- Be respectful and constructive.
- Prefer clear, actionable feedback.
- Assume good intent and collaborate to reach the best solution.
Thanks again for contributing to Event Scanner!