Contributing

This page mirrors the repository CONTRIBUTING.md for the documentation site. The source of truth for development gates is the markdown file at the repo root; keep them aligned when you change either.

Development environment

Rust 1.88 is the minimum supported toolchain; current stable runs the main test and lint gates. Documentation uses pixi:

cargo test --locked --lib
cargo test --locked --test reproduce_real_prs --test bump_emit
pixi run -e docs docbld

Code style and gates

  • cargo fmt --check

  • cargo clippy --all-targets -- -D warnings when you touch Rust

  • Tests relevant to your change must pass

  • New public CLI surface needs a flag entry in CLI reference and a unit or integration test under tests/

  • Known maintainer-bump regressions in tests/reproduce_real_prs.rs must stay green (library and CLI auto-bump)

Documentation

Primary docs live in orgmode under docs/orgmode/ (Diataxis). Edit there, then build. The Sphinx site includes an in-tree Rust API (crates/eb_stack/) via sphinx-rustdocgen + sphinxcontrib_rust (same path as rsx-rs).

# once: isolated system-Python environment for the native Rust extension
python3 -m venv .venv-docs
export RUSTFLAGS='-C linker=cc'
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=cc
.venv-docs/bin/pip install 'sphinx>=9,<10' shibuya sphinx-sitemap \
  sphinx-copybutton sphinx-design 'sphinxcontrib-rust>=1,<2' \
  'sphinx-rustdoc-postprocess>=0.1,<0.2'
cargo install sphinx-rustdocgen

export EB_STACK_DOCS_PYTHON=$PWD/.venv-docs/bin/python
pixi run -e docs docbld
scripts/check-doc-links.sh docs/build
pixi run -e docs linkcheck
# HTML -> docs/build/index.html

The Sphinx task treats warnings as errors. The rendered-link check rejects links to generated RST and incorrect source-edit targets; the Lychee task checks the rendered site and README links.

sphinxcontrib-rust contains a native Rust extension. The explicit linker environment keeps that extension on the host Rust/C linker rather than a linker injected by the documentation package environment.

Do not hand-edit generated docs/source/**/*.rst or docs/source/crates/.

Packaging campaigns

Follow AGENTS.md, skills/annual-bump/SKILL.md (generation rebuild), and skills/new-package/SKILL.md (conda-forge/Spack → new recipe). Run skills/verify-recipe/SKILL.md over what they emit before a build or a push, and skills/tool-repair/SKILL.md when the emitted file needed a hand correction: a manual fix that does not come back as a regression test is a defect this tool reproduces on the next run. Keep site hostnames, paths, credentials, scheduler sizing, and private module names in the site target layer. Public files contain reusable package intent and target topology.

Releasing

Version source of truth is version in root Cargo.toml. Keep these aligned:

  1. Cargo.toml / pixi.toml version

  2. CITATION.cff version and date-released for a published version

  3. docs/source/conf.py release

  4. CHANGELOG.md version heading and release date

Tag vX.Y.Z and push the tag. The release workflow builds the Linux archive and checksum and publishes the GitHub Release.