Contributing

This page covers both halves of contributing: the quality gates a code change has to pass, and the conventions the documentation follows.

Develop Shifty

Rust changes run the same gates CI does, from the repository root:

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

Python changes work from python/ against the locked development environment:

uv sync --dev --frozen --reinstall-package pyshifty
uv run ruff check .
uv run ruff format --check .
uv run ty check shifty
uv run pytest -q

--reinstall-package pyshifty is not optional when Rust sources have changed. The extension is installed as an editable build, and a plain uv sync will not rebuild it, so pytest silently exercises whichever _shifty shared object was compiled last. That produces failures against code you already fixed, and — more dangerously — passes against code you have not. Continuous integration is immune, because it always starts from a fresh checkout.

Fix diagnostics rather than weakening or skipping a check, unless a documented compatibility constraint requires a narrow exception.

The C++ SDK and the WebAssembly module have their own gates:

cmake -S cpp -B build/cpp -DSHIFTY_CPP_BUILD_TESTS=ON
cmake --build build/cpp
ctest --test-dir build/cpp --output-on-failure

Contribute to the documentation

Shifty’s documentation uses Diátaxis to keep pages focused, then applies the same lookup-friendly conventions throughout its reference material. Before writing, decide what the reader is doing.

Choose the page type

Type

Reader’s need

Writing rule

Tutorial

Learn through a successful first experience.

Lead the reader through a complete sequence. Explain only what the next step requires, and include checkpoints with expected output.

How-to guide

Accomplish a known, concrete task.

State the outcome first, list prerequisites, and give the shortest reliable procedure. Link elsewhere for theory.

Reference

Look up exact behavior while working.

Document signatures or syntax, stability, arguments and defaults, returns or output, errors, a minimal example, and related operations.

Explanation

Understand why the system behaves or is designed this way.

Develop the reasoning, alternatives, and tradeoffs. Do not turn the page into a procedure or an API inventory.

Page conventions

  • Give each page one primary reader goal and use that goal in its opening.

  • Write at the level of the subject. State the technical fact directly; avoid narrating the teaching strategy or telling readers what they will find surprising, confusing, or important.

  • Put exact defaults, accepted values, failure behavior, and stability in the reference page—not only in examples or source comments.

  • Link to related capabilities and useful next steps. When a tutorial or how-to guide introduces an interface, include a forward pointer to its reference page for exact fields, arguments, and behavior. Prefer links over repeating an explanation in several places.

  • Mark experimental interfaces wherever a reader first encounters them.

  • Use a figure only when it makes a relationship, sequence, or state change clearer than a short paragraph or table. Keep figures as scalable SVGs in docs/_static, add SVG title and desc elements, and supply useful alternative text in the Sphinx figure directive.

Executable examples

Key examples live in docs/examples as runnable files. Include their source with literalinclude and their output with program-output so the page cannot show code from one program and output from another. Keep these examples offline, deterministic, and fast. Sort values before printing if an API does not guarantee their order.

Use ordinary code-block directives for fragments, invalid-input examples, installation commands, network access, and operations that are too expensive or environment-dependent to run during every documentation build.

Preview your changes

From the repository root:

cd docs
make html SPHINXOPTS="-W --keep-going"

The normal build does not rewrite benchmark source data. To regenerate the benchmark chart deliberately before building, set SHIFTY_REGENERATE_BENCHMARKS=1.

Every rendered page has an Edit this page link to its source on GitHub. For a change that needs discussion first, open an issue.