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: system-cargo venv (conda mold cannot link sphinxcontrib-rust)
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.

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). 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.