Contributing Guide

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

Getting Set Up

  1. Contact SiliconGhetto with the change you want to make.
  2. Work from the source package or private repository access provided for that change.
  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 the change for review — 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 platform 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?

Review 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.