Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
76 lines (63 loc) · 3.79 KB

CONTRIBUTING.md

File metadata and controls

76 lines (63 loc) · 3.79 KB
Raw

Contributing to Wright

Wright is being built incrementally. Read AGENTS.md, architecture.md, compatibility.md, and licensing.md before changing compiler boundaries or integration verification.

Toolchain policy

The repository builds with one fixed toolchain, pinned in rust-toolchain.toml. rust-version in the workspace manifest and every CI job use the same version. Wright ships binaries and publishes no crate, so it has no minimum supported Rust version.

Raise the toolchain by changing rust-toolchain.toml, rust-version, and the toolchain: entries in .github/workflows together.

Local checks

Run the same checks used by CI from the repository root:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features

Wright-specific Rust policy

The workspace lint baseline in Cargo.toml is intentionally small. rustc/rustfmt and the normal Clippy defaults continue to own mechanical style; the workspace also denies unsafe operations that are not explicitly scoped, unreachable public items, correctness/suspicious Clippy findings, and unfinished development macros. Performance findings stay warning-level locally and are errors in the CI commands above. The policy does not enable Clippy's pedantic, nursery, or restriction groups.

This policy was audited against the workspace manifests, CI, and representative compiler/tooling crates (wright-driver, wright-language, and wright-lsp):

  • Semantic identities use typed IR IDs and arena lookups; raw strings remain at protocol, source-name, and presentation boundaries. New public contracts should use a typed representation when two raw values could be confused.
  • Observable ordering uses insertion-ordered arenas or ordered collections at output/service boundaries. Hash maps and sets remain appropriate for private lookup and membership indexes, but their iteration order must not leak into a compiler or tooling result.
  • Diagnostics are structured driver/language-service data. Human-readable rendering belongs in the CLI/LSP presentation boundary and must not become a substitute for a machine contract.
  • Existing unwrap/expect calls are concentrated in invariant-checked compiler paths, serialization boundaries, benchmarks, and tests. They are reviewed by context; Wright does not impose a blanket ban. New fallible compiler behavior should return a structured error instead of panicking.
  • Shared interior mutability, broad cloning, complex lifetimes, and dynamic dispatch require a concrete ownership or API reason. Do not add them merely to avoid designing that boundary.
  • The only current unsafe operation is the benchmark's platform-specific getrusage measurement. New unsafe code requires a concrete need, a local invariant comment, focused tests, and the smallest possible unsafe surface. Dependencies must preserve the crate dependency direction.

Change conventions

  • Keep changes within the owning package or documented boundary.
  • Add regression coverage at the lowest layer that proves the behavior.
  • Record material contract changes in a new ADR instead of silently rewriting an accepted decision.
  • Preserve provenance and licensing information for external fixtures, generated artifacts, and dependencies.
  • Keep commits focused on one functional boundary and do not include unrelated working-tree changes.
  • Describe planning work by concrete capability, issue reference, or release version (normative pre-1.0 contract: architecture/product-contract.md); internal phase-number labels are not the roadmap model for new issues, PRs, or living docs.