Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (79 loc) · 4.92 KB

CONTRIBUTING.md

File metadata and controls

109 lines (79 loc) · 4.92 KB

Contributing to mlxcel

Thank you for your interest in contributing to mlxcel! This document covers the basics for getting started. For the deeper working contract — invariants for the request path, MLX upstream pin synchronization, model-porting checklist — read AGENTS.md after this.

Quick links

You want to... Read
Report a security vulnerability SECURITY.md — do not open a public issue
File a bug or feature request GitHub Issues (use the templates)
Build and test locally docs/installation.md
Understand the architecture docs/architecture.md
Add a new model family docs/adding-models.md
Understand the project conventions AGENTS.md

How to contribute

Reporting issues

  • Search existing issues first.
  • Use the bug-report or feature-request template — they prompt for the information we need to act on the issue.
  • Include the mlxcel version (mlxcel --version), platform (macOS Apple Silicon / Linux CUDA + GPU model), and the checkpoint you were running.
  • For inference correctness or performance reports, also include the prompt and seed so the run is reproducible.

Submitting pull requests

  1. Fork the repository and create a feature branch off main: 
    git checkout -b feat/short-description
  2. Make your changes. Keep one PR scoped to one logical change — a model port, an MLX bump, and a CLI rename are three PRs.
  3. Build and test for your target: 
    # macOS (Apple Silicon)
cargo build --release --features metal,accelerate
cargo test --release

# Linux / CUDA
cargo build --release --features cuda
cargo test --release
  4. Run the local quality gates: 
    cargo fmt --all -- --check   # enforced by CI; fmt violations block merge
cargo clippy --all-targets -- -D warnings
cargo deny check             # advisories + licenses + sources
  5. For inference changes, validate against a real checkpoint — synthetic or build-only validation is not enough (see AGENTS.md for why).
  6. Commit with a conventional prefix (see below) and a clear message.
  7. Push to your fork and open a Pull Request. The PR template will prompt for a summary, test plan, and linked issues.

Commit and PR conventions

Write commits, PR titles, and issue comments in English. Use Conventional Commits prefixes:

Prefix When
feat: New user-visible feature
fix: Bug fix
perf: Performance improvement with measurable evidence
refactor: Internal restructuring without behavior change
chore: Build, CI, dependencies, release infrastructure
docs: Documentation
test: Tests only

Code standards

  • Follow standard Rust conventions: rustfmt, clippy -D warnings, idiomatic ownership and error handling.
  • Tests live next to the code (_tests.rs files) for unit tests, and under tests/ for end-to-end integration.
  • When modifying a function shared by multiple models, update the // Used by: Model1, Model2, … comment above it. See docs/code-guidelines.md.
  • Do not introduce Python on the inference request path. Python is acceptable only for benchmarks and out-of-band tooling.

Adding a new model family

See docs/adding-models.md for the full checklist. The short version: land one working checkpoint plus tests before broadening, mirror the mlx-lm / mlx-vlm directory shape where it helps, and update docs/supported-models.md plus the detection table in src/models/detection.rs.

Bumping the MLX upstream pin

The pinned MLX C++ commit lives in three files that must stay in sync — see the "MLX upstream commit upgrade" section of AGENTS.md for the list and the mandatory post-bump validation.

Development environment

Detailed setup instructions are in docs/installation.md.

Minimum:

  • Rust 1.93+ (project uses edition 2024)
  • macOS: Apple Silicon Mac on macOS Sonoma+; Xcode Command Line Tools
  • Linux: CUDA 13+ toolchain, OpenBLAS, LAPACK (see docs/installation.md for the package list)

Recommended local tooling:

cargo install cargo-deny --locked
cargo install cargo-audit --locked

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to abide by its terms.

Questions

License

By contributing to mlxcel, you agree that your contributions will be licensed under the Apache License 2.0.