CONTRIBUTING.md~4 min readContributing to Mimikyu
Welcome, traveler, to the Haunted Rag Workshop! Whether you are fixing a subtle WebDriver BiDi frame edge case, sharpening @eN accessibility snapshots, improving docs, or reporting a bug from the field, we are thrilled to have you here.
mimikyu moves fast while keeping main rock-solid by pairing warm, ego-free collaboration with crisp architectural boundaries (see ARCHITECTURE.md). This guide shows you how to equip your dev gear, run the local test gauntlets, and open pull requests that breeze through review on the first pass.
Before You Start: Scope & Community Ground Rules
- Be kind and constructive: All interactions are governed by our Code of Conduct.
- Security vulnerabilities: Never post exploitable security bugs in public issues—use Private Vulnerability Reporting as documented in SECURITY.md.
- Strict R3 Scope Boundary:
mimikyuis a legitimate AI-agent browser runtime and isolation toolkit. We do not accept issues, discussions, or PRs related to CAPTCHA solvers, human-verification ("verify you are human") bypasses, proof-of-work crackers, or anti-bot gate circumvention. - Right-size your quest: For bug fixes, docs, or small enhancements (1–2 modules), jump straight to a PR! For new CLI subcommands, new MCP tools, or changes to
DriverSession, open a[Feat]Issue or Discussion first so we can align on the interface before you write hundreds of lines of code.
1. Equipping Your Dev Gear (Quick Local Setup)
Prerequisites
- Rust
1.88+(edition = "2024") via rustup:rustup update stable rustup component add clippy rustfmt - Local Browsers: At least one local Chromium / Google Chrome and Firefox installation (system install, Playwright/Puppeteer cache, or explicit
MIMIKYU_CHROMIUM_PATH/MIMIKYU_FIREFOX_PATHenv vars). - Python 3 (
3.9+): Standard library only (zeropippackages needed!) for running the opaque-boxe2e/test suite.
Clone, Build & Check Your Environment
git clone https://github.com/YXZYSME/mimikyu.git
cd mimikyu
# Build release binary and run browser discovery diagnostics
cargo build --release
./target/release/mimikyu doctor
./target/release/mimikyu doctor --json
If mimikyu doctor finds both Chromium and Firefox, your workstation is ready for full dual-engine testing!
2. Running the Verification Gauntlet
Every automated test in mimikyu runs 100% offline against ephemeral 127.0.0.1:0 loopback servers (crates/mimikyu-core/src/harness/ and e2e/local_server.py).
Fast Inner Loop (While Coding)
# Check formatting and strict zero-warning Clippy lints
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
# Run a single crate test binary while iterating on a module
cargo test -p mimikyu-core --lib
cargo test -p mimikyu-core --test snapshot_test
cargo test -p mimikyu-cli
Full Pre-PR Verification Suite
Before marking a PR ready for review, run the three verification tiers:
# Tier 1: Workspace Rust unit, integration, and CLI contract tests
cargo test --workspace
# Tier 2: Build release binary & run E2E harness self-checks
cargo build --release
python3 e2e/run_e2e.py --self-test
# Tier 3: Full Chromium E2E (Tiers 1-4) + Firefox WebDriver BiDi E2E (Tier 4)
python3 e2e/run_e2e.py --tier all --bin ./target/release/mimikyu
python3 e2e/run_e2e.py --tier 4 --engine firefox --bin ./target/release/mimikyu
If your change touches performance-critical hot paths (snapshot/, extract/, input/, isolation/virtual_ctx.rs, driver/), also verify local benchmarks:
./target/release/mimikyu bench --iterations 3 --warmup 1 --suite all
3. Conventional Commits & Branch Naming
We use Squash and Merge on main with Conventional Commits so CHANGELOG.md and SemVer releases stay crisp and auditable.
Branch Naming
feat/<short-slug>— new capability (e.g.,feat/snapshot-landmark-roles)fix/<short-slug>— bug fix (e.g.,fix/bidi-iframe-scroll-bounds)docs/<short-slug>— documentation or examplestest/<short-slug>— unit or E2E test coveragerefactor/<short-slug>/perf/<short-slug>/ci/<short-slug>
Commit & PR Title Format
<type>(<optional-scope>): <imperative summary in <= 72 chars>
Examples:
feat(extract): preserve colspan headers in markdown table exportfix(bidi): sanitize lone UTF-16 surrogates in script evaluation framesperf(snapshot): preallocate AxNode arena for deep Shadow DOM treesdocs(architecture): clarify ChokepointInput ACK timeout guaranteestest(e2e): add cross-origin nested iframe fill regression check
4. Five Rules for PRs That Breeze Through Review
Read ARCHITECTURE.md for the full design rationale. In summary, reviewers check every PR against five invariants:
- Keep PR slices narrow (2–3 modules max):
- Touch only the modules needed for one coherent vertical slice plus its tests. Don't mix sweeping formatting diffs or unrelated refactors into feature PRs.
- Respect
DriverSession&ChokepointInputboundaries:- Keep CDP (
driver/cdp.rs) and WebDriver BiDi (driver/bidi.rs) wire details strictly insidedriver/. - Route all pointer, keyboard, and wheel actions through
ChokepointInput(input/chokepoint.rs)—never call rawdispatch_*methods directly fromsession.rs,mcp/, orcli/.
- Keep CDP (
- Preserve Dual-Engine Parity:
- Verify behavior on both Chromium (CDP) and Firefox (WebDriver BiDi), or gate genuinely unsupported features cleanly via
DriverCapabilities+MimikyuError::Unsupported.
- Verify behavior on both Chromium (CDP) and Firefox (WebDriver BiDi), or gate genuinely unsupported features cleanly via
- Zero Orphans, Zero Crash Popups, Zero Flaky Sleeps:
- Spawn processes exclusively through
ProcessGuard(setpgid(0, 0)), preserve macOS zero-spawn Firefox plist/application.iniprobing andMOZ_CRASHREPORTER_DISABLE=1, and use deterministic waits (WaitEngine) instead of arbitrarysleep()calls.
- Spawn processes exclusively through
- Strict Hygiene & Supply-Chain Discipline:
- Never hardcode personal machine paths, usernames, or private LAN IPs in code, snapshots, or docs.
- Avoid adding new crate dependencies unless truly necessary; any new dependency must pass
cargo deny checkagainstdeny.toml(crates.ioonly, permissive license allowlist).
Licensing of Contributions
mimikyu is dual-licensed under MIT OR Apache-2.0 (LICENSE-MIT and LICENSE-APACHE). Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository by you shall be dual-licensed as above, without any additional terms or conditions.