Skip to content

contributing.org

Latest commit

 

History

History
95 lines (75 loc) · 3.89 KB

contributing.org

File metadata and controls

95 lines (75 loc) · 3.89 KB
Raw

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. Site administrators start at Get started and Installation. The shard and inode model is Sharding and inode admission.

Development environment

Rust 1.90 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. Shared names (closure, generation, baseline, the claim ladder) are in the glossary. 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 the build, test, lint and docs commands at the repository root, 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 return 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 (currently 0.7.4). Keep these aligned:

  1. Cargo.toml / pixi.toml version
  2. pyproject.toml version and server.json (both version fields)
  3. CITATION.cff version
  4. docs/source/conf.py release
  5. CHANGELOG.md version heading and release date
  6. CITATION.cff date-released when the version is published

tests/public_metadata.rs rejects a date-released line, so that field stays absent until the test is updated for a published citation.

Tag vX.Y.Z and push the tag. .github/workflows/release.yml (cargo-dist) builds the installers and publishes the GitHub Release. It does not publish to crates.io.