CONTRIBUTING.md

Contributing to Zapcode

Thanks for your interest in contributing to Zapcode!

Getting started

Prerequisites

• Rust (stable)
• Node.js 18+ (for JS bindings)
• Python 3.10+ (for Python bindings)

Build from source

git clone https://github.com/TheUncharted/zapcode.git
cd zapcode
cargo build
cargo test

Run benchmarks

cargo bench -p zapcode-core

Development workflow

1. Fork the repo and create a branch from master
2. Make your changes
3. Run make lint and make test to verify
4. Submit a PR

Commit messages

We use Conventional Commits for automated releases:

• feat: add Promise.all support → minor version bump
• fix: snapshot resume with nested arrays → patch version bump
• feat!: rename API method → major version bump (post-1.0)

Code style

• cargo fmt for formatting
• cargo clippy -- -D warnings must pass with zero warnings
• No unsafe without a // SAFETY: comment

Architecture

See AGENTS.md for the full architecture reference before making changes to the core.

Key rules:

• zapcode-core is pure Rust with zero I/O — no filesystem, network, or env access
• Binding crates (zapcode-js, zapcode-py, zapcode-wasm) only marshal types — no business logic
• Every new instruction needs correct stack discipline and resource limit checks

Testing

• Write tests before considering a feature done
• Core tests: cargo test -p zapcode-core
• Security tests: cargo test -p zapcode-core --test security
• E2E JS: cd crates/zapcode-js && npm install && npx napi build --release --platform --js index.js --dts index.d.ts && cd ../../examples/typescript/basic && npm install && npx tsx main.ts
• E2E Python: cd crates/zapcode-py && maturin develop --release && cd ../../examples/python/basic && python main.py

Reporting issues

• Use GitHub Issues
• Include a minimal reproduction if possible
• For security vulnerabilities, email directly instead of opening a public issue

License

By contributing, you agree that your contributions will be licensed under the MIT License.