Contributing Guide

Contributions to SiliconGhetto are welcome. This guide covers the process and expectations.

Getting Set Up

  1. Fork the repository on GitHub
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/siliconghetto.git
  3. Install prerequisites (see Getting Started)
  4. Create a branch: git checkout -b your-feature

Development Process

  1. Open an issue first — describe what you want to change and why. This avoids duplicate work and lets us discuss the approach before you invest time.
  2. Write code — implement your change with tests where appropriate.
  3. Ensure all checks pass: 
    cargo fmt --all
cargo clippy --workspace -- -D warnings
cargo test --workspace
  4. Submit a pull request — reference the issue, describe what changed, and explain your testing approach.

Code Standards

Formatting

  • Run cargo fmt before committing. CI enforces this.
  • Use the default rustfmt configuration (no .rustfmt.toml overrides).

Linting

  • cargo clippy -- -D warnings must pass with no warnings.
  • Fix clippy suggestions rather than suppressing them unless there’s a good reason.

Testing

  • Add tests for new functionality.
  • Unit tests live next to the code they test (in #[cfg(test)] mod tests).
  • Integration tests go in the crate’s tests/ directory if needed.
  • All tests must pass on stable Rust.

Commit Messages

  • Use the imperative mood: “Add sprite batching” not “Added sprite batching”
  • Keep the first line under 72 characters
  • Reference issues when relevant: “Fix #42: handle zero-size viewport”

What to Contribute

Good First Contributions

  • Documentation improvements
  • Test coverage for existing code
  • Clippy lint fixes
  • Demo improvements

Larger Contributions

  • New engine features (discuss in an issue first)
  • Performance optimizations (include benchmarks)
  • New demos showcasing engine capabilities
  • Browser compatibility improvements

Platform Code

Platform code (platform/) is under a different license (LICENSE-PLATFORM). Contributions to platform code grant the project maintainers broad rights to relicense. See the license file for details.

Architecture Decisions

Significant architectural changes should be proposed as ADRs (Architecture Decision Records) in docs-content/adr/. The format is:

  1. Context — what problem are we solving?
  2. Options considered — what alternatives exist?
  3. Decision — what did we choose and why?
  4. Consequences — what are the trade-offs?

Pull Request Checklist

  • Code compiles without warnings (cargo check)
  • All tests pass (cargo test)
  • Code is formatted (cargo fmt)
  • Clippy is clean (cargo clippy -- -D warnings)
  • New code has appropriate tests
  • Documentation is updated if behavior changed
  • Commit messages are clear and descriptive

License

By contributing to SiliconGhetto:

  • Engine code contributions (crates/, demos/) are licensed under MIT OR Apache-2.0
  • Platform code contributions (platform/) are subject to the LICENSE-PLATFORM terms
  • Documentation contributions are licensed under MIT OR Apache-2.0