# Contributing
Use `devenv shell` to enter the environment pinned to Rust 1.89.0. The core Rust
library supports Rust 1.84, and the Python extension supports Rust 1.85. Some
optional backends and development dependencies require newer Rust, so use the
pinned toolchain for tests and benchmarks. CI checks the MSRV separately by
building the compatible library features and Python extension without
development dependencies. The library uses the Rust 2021 edition and the Rust
2024 formatting style. Documentation uses `docs/diplodocus.yaml` and the
`nightly-2026-09-28` extraction toolchain. Devenv pins Diplodocus 0.6.0 with
compatibility patches for generated input exclusions and native GFM math. CI
installs the prebuilt Diplodocus 0.9.0 release through
`jolars/setup-diplodocus@v1`, which includes native GFM math, and keeps its
Python environment outside the checkout.
## Releases
Versionary manages Rust and Python releases independently. CI uses the
`RELEASE_TOKEN` secret to create release pull requests and tags after the checks
pass. Rust releases use `v*` tags; Python releases use `shrinkage-python-v*`
tags.
The `Publish Crate` workflow publishes the root Rust package to crates.io when a
`v*` tag is pushed. To retry a release manually, run the workflow with that tag
selected. Publishing runs `cargo publish --locked` with the pinned Rust
toolchain and uses the GitHub `release` environment.
Configure a [crates.io trusted
publisher](https://crates.io/docs/trusted-publishing) for the `shrinkage` crate
with repository owner `jolars`, repository `shrinkage`, workflow filename
`publish-crates.yml`, and environment `release`. The workflow obtains a
temporary publishing token through GitHub OIDC, so it does not require a
crates.io token secret. Python release tags do not trigger this workflow.
The `Publish Python` workflow builds wheels for CPython 3.11 through 3.15 on
Linux and Windows x86-64 and on macOS Intel and Apple Silicon. It tests every
wheel and rebuilds and tests the source distribution before publishing to PyPI.
Python releases use `shrinkage-python-v*` tags. Manual runs on branches build
and test artifacts; manual runs on a matching Python release tag also publish
them.
For the first PyPI release, register a [pending trusted
publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
from your PyPI account's [Publishing
settings](https://pypi.org/manage/account/publishing/). Use project name
`shrinkage`, owner `jolars`, repository `shrinkage`, workflow filename
`publish-python.yml`, and environment `release`. The first successful upload
creates the project and activates its publisher. Later releases use the same
configuration, with no PyPI token secret required.
## Python package
The optional package lives in `packages/python`. Its native crate and Cargo
lockfile are independent of the root Rust package. Maintained Python source and
stubs under its `src/shrinkage` directory supply the Python reference. The
install task rebuilds the editable native extension so checks include Rust
source changes.
```console
task python:install
task python:check
task python:artifacts
```
The artifact check installs a wheel into a fresh environment, tests it outside
the checkout, and repeats the checks after rebuilding a source distribution. The
private native smoke function exercises Rust penalty evaluation, and the dense
input tests verify validation, layouts, snapshots, and ownership against each
installed artifact. Public lasso tests compare fitting, preprocessing,
diagnostics, and prediction with Rust fixtures and independent optimality
calculations. A concurrency test verifies GIL release and snapshot independence.
`task example` checks that the committed fixtures match the current Rust API.
Use `task format` to format Rust, Python, and Markdown. `task check` runs the
complete Rust and Python checks. The Python package does not install or build as
part of a plain root `cargo build`.
The [Python lasso
benchmark](https://github.com/jolars/shrinkage/tree/main/packages/python/benchmarks)
compares one regularization strength with scikit-learn through Metewand. Run it
with
`compute bench --reason "Python lasso comparison" -- devenv shell -- task python:bench`.
This updates the convergence plot and retained measurements for the authored
Python docs, using linear fit time and the independently evaluated duality gap.
`task python:bench:check` checks the report and saved figure without rerunning
the benchmark. Benchmark dependencies belong to the optional `benchmark` group.
## Documentation
Edit this guide in the root `CONTRIBUTING.md`. Documentation tasks and CI copy
it to `docs/pages/contribution.md` before building the site.
```console
task docs:serve
task docs:build
task docs:check
task docs:figures
```
These tasks prepare the editable Python package and fetch the root Rust
dependencies before invoking Diplodocus. Native Rust extraction and doctests
then run with locked, offline dependency resolution. Documentation builds also
execute the Python package's doctest against the prepared checkout.
The Reference section lives under `docs/pages/reference`. Write inline math with
`$...$` and display equations with `$$...$$`. Diplodocus renders native KaTeX
during the build and bundles its CSS and fonts, including MathML for accessible
equations. Check the built pages for `math-fallback` markers after adding new
commands.
`task docs:figures` regenerates the committed SVG penalty regions with pinned
Matplotlib and NumPy dependencies. The generator fixes its metadata and SVG
identifiers and checks boundary, interior, and exterior samples.
`task docs:figures:check`, also run by `task docs:check`, verifies that the
committed figures are current. The page captions record the plotted strengths,
groups, and coefficient layouts.
`task docs:check` validates the generated Worker package without deploying it.
To test deployment routing locally, run `npm --prefix docs run preview` after
building. Generated site output, environments, and caches are ignored.
The documentation workflow builds every push and pull request, and deploys
successful `main` builds to `https://shrinkage.cc/`. It uses the repository's
`CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` secrets. Manual workflow runs
deploy only when they target `main`.