scverse / scverse/rustar-aligner

docs: add DEPENDENCIES.md recording accepted and declined crates

Open
#209 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Rust
Stars
75
Forks
7
Avg merge
8m
Merged PRs (30d)
1

Description

CONTRIBUTING.md:58 requires that a new dependency, especially a non-Rust one, be raised in an
issue before the PR. That rule covers the decision. What it does not cover is the record: today
the justifications live in comments in Cargo.toml (good ones, for flate2's zlib-rs backend
and for mimalloc) and the rejections live nowhere at all. So a crate that was considered and
turned down in issue #N gets re-proposed six months later and re-litigated from scratch.

Proposal: a DEPENDENCIES.md at the repo root with two tables and one list.

  1. Active runtime dependencies — crate, version range, license, what uses it, why it earns its
    place. Seeded from the comments already in Cargo.toml, which are the best material here.
  2. Dev-only dependencies — same shape, lower bar (nothing ships).
  3. Considered and declined — crate, date, reason, link to the deciding issue.

Declined list, from the August 2026 survey

Draft content for section 3, to be confirmed in the sibling issues:

  • Alternative alignersblock-aligner 0.5.1 (adaptive SIMD affine-gap, 5–10x over prior
    methods on its paper's datasets), ksw2rs, parasailors. Faithfulness to STAR's scoring,
    extension and tie-breaks is the product; an aligner that computes alignments differently, even
    better, is a divergence.
  • k-mer / minimizer / sketching cratessimd-minimizers, minimizer-iter,
    minimizer-queue, seq-hash, sourmash, nthash. STAR seeds by MMP search in the suffix
    array; sketching changes which seeds exist.
  • rust-htslib — brings htslib as a system C dependency; noodles already covers
    SAM/BAM/BGZF with a self-contained build across the five supported platforms.
  • rust-bio — broad toolkit, slower readers (allocations, copying, UTF-8 validation), few
    pieces needed.
  • Interval librariessuperintervals, coitrees, rust-lapper; see the sibling issue,
    including their non-standard license flags.
  • Succinct / rank-select librariessucds, vers-vecs, sux, bitm. The packed index
    layout is dictated by STAR's format and there is no rank/select query need.
  • rkyv — the index layout is externally specified, not a serialization of our own types.

Checklist

  • Write DEPENDENCIES.md with the three sections
  • Seed section 1 from the existing Cargo.toml comments, then trim the comments to a pointer
  • Link it from CONTRIBUTING.md next to the "new dependencies need prior discussion" rule
  • Backfill the decided issues (#162 and the siblings of this one) into section 3 as they close

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the dependency comments in Cargo.toml, the rule at CONTRIBUTING.md:58, issue #162, and the sibling issues named in the proposal. Create the root DEPENDENCIES.md with active, dev-only, and considered-and-declined sections; trim Cargo.toml comments to point to it, link it from CONTRIBUTING.md, and backfill decided issues as they close.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.