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.

Branding And Trademark Safety

  • Do not use third-party franchise names, product names, trademarks, or borrowed block-world terminology anywhere in this repo.
  • If a branded term appears in code, docs, demos, comments, assets, or UI copy, stop and replace it immediately with SiliconGhetto-native wording before continuing other work.
  • Run pnpm run guard:terms after changing public APIs, docs, examples, demos, or branding-sensitive copy.

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

License Note

All code in this repository is proprietary and source-available under the SiliconGhetto Source-Available License. See the LICENSE file for full terms.

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, you agree to the terms of the SiliconGhetto Source-Available License (see LICENSE). Your contributions grant the copyright holder a perpetual, worldwide, irrevocable, royalty-free license to use, modify, sublicense, and distribute your contributions under any license terms.