Contributing

candding is a small repository with strict conventions, because the thing it promises, vectors that match the reference, only survives if every change is verified the same way. This page is what you need before the first commit; porting a model and testing cover the two workflows that have more to them than a recipe.

Toolchain

• Stable Rust, at or above the rust-version field in the workspace Cargo.toml.
• A nightly toolchain for the formatter only: the repository's rustfmt.toml uses unstable options, so formatting is always cargo +nightly fmt.
• just as the command runner; every workflow in this repository is a recipe.
• uv for the Python reference scripts, which run through uv run --project scripts and never need a manual virtual environment.
• The hf CLI for downloads, from pip install huggingface_hub or uv tool install huggingface_hub.
• Bun for this documentation site.

Recipes

Conventions

• Commit subjects are <type>: <imperative subject> with no scope and no trailing period, one logical change per commit, and no trailers of any kind.
• Rust files stay under three hundred lines, and main.rs holds only main; a file that grows past that becomes submodules rather than a longer file.
• Comments are doc comments plus the rare short note about why something is done a particular way. No banner comments, no restating the code, no commented-out code.
• The library never prints: diagnostics go through tracing, and println! belongs to the CLI.
• Model code has no #[cfg] and no device checks; the one backend branch lives in the shared attention function.
• Everything is written in English, and Markdown is not hard-wrapped: one paragraph is one line.

Skills

The repository carries six skills that encode the workflows an agent or a new contributor would otherwise have to rediscover.

• porting-embedding-model: the repository files to read before a port, the family checklist and the numerical pitfalls. The porting guide is its public form.
• golden-vector-testing: the fixture layout, the generator, the tolerance policy and how to bisect a mismatch layer by layer.
• hf-model-download: the download commands and include patterns, the cache layout, revisions, gated repositories and tokens.
• device-compat: the feature matrix, default dtypes, where a backend branch is allowed, known accelerator gaps and how to run parity.
• commit-workflow: what must pass before a commit, the message format, and what never goes into one.
• docs-writing: the frontmatter contract, the shape of each page type and the checks this site is held to.

CI

The two golden models in CI are the small English bge model and MiniLM, which keeps the cached download small; the rest of the catalog is verified locally before a model commit lands.