Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (97 loc) · 4.76 KB

CONTRIBUTING.md

File metadata and controls

121 lines (97 loc) · 4.76 KB
Raw

Contributing to eb-stack

Thank you for your interest. eb-stack turns conda-forge, Spack, and EasyBuild inputs into source-evidenced SBOMs, Resolvo locks, conventional EasyBuild variants, and persisted build campaigns. Clear, tested, reproducible changes win.

Development environment

Rust 1.90 is the minimum supported toolchain; current stable is used for the main test and lint gates. pixi provides docs and optional dev tasks:

cargo test --locked --lib
cargo test --locked --test reproduce_real_prs --test bump_emit
prek run -a                   # or: pixi run -e dev prek
pixi run -e dev check         # fmt + clippy + lib tests
pixi run -e docs docbld       # orgmode to rst to Sphinx (Shibuya)

Build heavy work on a remote builder when local compiles thrash the machine.

Code style and gates

  • prek run -a (trailing whitespace, YAML/TOML, codespell, large files)
  • cargo fmt --check
  • cargo clippy --all-targets -- -D warnings when you touch Rust
  • All tests relevant to your change must pass
  • New public CLI surface needs a flag in docs/orgmode/reference/cli.org and either a unit test or an integration test under tests/
  • Known maintainer-bump regressions live in tests/reproduce_real_prs.rs and must stay green (library and CLI auto-bump)

Documentation

Primary docs live in orgmode under docs/orgmode/ (Diataxis). Edit there, then build:

# 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   # or use an existing ~/.cargo/bin copy

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 to docs/build/index.html (includes crates/eb_stack/* Rust API)

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 skills/annual-bump/SKILL.md (generation rebuild) and skills/new-package/SKILL.md (conda-forge/Spack: new EasyBuild 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. The public files contain reusable package intent and target topology.

Releasing

Version source of truth: version in root Cargo.toml (currently 0.7.4). Keep these in lockstep on every release:

  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: move Unreleased notes into ## X.Y.Z - YYYY-MM-DD
  6. CITATION.cff: add date-released when the version is published
  7. The version a recorded command prints: README.md, this file, docs/orgmode/index.org (the install section), docs/orgmode/install.org, docs/orgmode/get-started.org, docs/orgmode/contributing.org, docs/orgmode/changelog.org, and docs/orgmode/explanation/sbom-blast-radius.org, whose eb-stack --version block tests/sbom_page_drift.rs compares with a fresh run; then python scripts/gen-llms-txt.py for llms-full.txt

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

Then:

git tag -a v0.7.4 -m "eb-stack 0.7.4"
git push origin v0.7.4
# .github/workflows/release.yml (cargo-dist) builds the installers
# and publishes the GitHub Release.
# .github/workflows/publish.yml publishes eb_stack to crates.io with Trusted
# Publishing and then registers the MCP server (mcp_registry.yml). It skips a
# version already on crates.io. Until crates.io lists stackhands/eb-stack as a
# Trusted Publisher, publish by hand from the tagged checkout, then run the
# mcp-registry workflow:
cargo publish --locked

Verify the binary surface:

cargo build --release
./target/release/eb-stack --version
# prints eb-stack 0.7.4