Contributing to SimurgArray

Thank you for looking. SimurgArray is a small research project with strict habits, because its main promise is that every number can be checked. The rules below keep that promise.

Before you start

Read the item in SIMURGARRAY_FUNCTIONAL_SPEC.md that your change touches. Behaviour is defined there item by item (IDs such as CLI-021 or OUT-031); algorithms and their sources are in SIMURGARRAY_MASTER_PLAN.md.
For anything larger than a small fix, open an issue first and describe the change and how you will validate it.

Setting up

git clone https://gitea.yaylali.uk/kemal/SimurgArray.git && cd SimurgArray
uv venv && uv pip install -e ".[dev]"
uv pip install ./rust/simurg-core          # optional compiled kernels (needs Rust and a C compiler)
uv run pytest tests/unit

The checks every change must pass

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest tests/unit

CI runs the same checks, a secret scan, and the unit tests with and without the compiled kernels on Python 3.12 and 3.13. If your change touches file formats, calling, QC or outputs, also run the oracle tests (uv run pytest tests/oracle, see the README for the data they need) and say which ones you ran.

Rules of the house

Cite the spec. Commit messages and tests name the spec items they implement or change. If behaviour changes, change the spec item in the same commit.
Science modules are pure. Code under signal/, genotype/, cn/, qc/, pgx/ and train/ has no file or network access; the pipeline/ layer does the I/O.
Every algorithm names its source in its docstring: a paper, a public technical note, an expired patent, or an open source project with a compatible licence.
Licences. Code from MIT, BSD, Apache 2.0 or Unlicense projects may be adapted with attribution in THIRD_PARTY_NOTICES.md. GPL tools are used only as separate programs for comparison; their code is never copied.
Exact by default. Default mode stays bit exact with the reference outputs. A cleaner numerical choice goes behind an explicit option.
Never hide a difference. When SimurgArray and a reference tool disagree, record it in docs/known_unknowns.md with the date, the evidence and what was decided.
No vendor data and no secrets in the repository. No IDAT, BPM, CSV, EGT or GTC files from a vendor, no probe name lists derived from them, no patient or participant data, and no credentials of any kind. Test fixtures are synthetic or openly licensed. .gitignore and the CI secret scan help, but the responsibility is yours.
Plain writing. Documentation follows the voice in branding/README.md: short sentences, numbers instead of adjectives, and every claim next to its limitation.

Checking numbers before publishing

Text that quotes results (README, user guide, blog posts, announcements) is checked against the validation reports before it goes out:

python scripts/docs/check_claims.py README.md blog/*.md docs/user_guide.md my_draft.txt

Code finds every sentence or table row with a number and the passages in docs/validation/, docs/known_unknowns.md and the spec that share it; a TypeSafe System One model only judges whether each passage supports, contradicts or says nothing about the claim. claims_report.md lists contradicted claims, claims without a source, low confidence cases for a person to read, and verified claims. Only this repository's documentation text is sent to the API, never data. The key comes from TYPESAFE_API_KEY or ~/.config/typesafe/credentials and never enters the repository; a full check costs well under one cent. --dry-run shows the claims and evidence without calling the API.

Maintenance tools (TypeSafe Jev)

Small tools in scripts/jev/ use TypeSafe System One judgments (Jev) where plain code needs semantic understanding. Code always collects the evidence and decides what to do; the model only answers typed questions. They are never part of the simurg commands, which stay offline. The key comes from TYPESAFE_API_KEY or ~/.config/typesafe/credentials (a repository secret of the same name for the issue workflow).

scripts/docs/check_claims.py FILES: numeric claims of public texts against the validation reports.
scripts/jev/spec_coverage.py: which spec items have a test; writes spec_coverage_report.md.
scripts/jev/voice_check.py FILES: brand voice rules (dashes, banned words, claims without limits, hype, tone).
scripts/jev/nightly_triage.py NIGHT: which known finding explains a failed nightly step; scripts/nightly.py runs it automatically when a night fails.
scripts/jev/issue_triage.py: first triage of new issues (.gitea/workflows/issue_triage.yml).
scripts/jev/literature_watch.py: weekly reading list from bioRxiv and PubMed into data/literature/.

Each run costs a fraction of a cent; answers are cached in .cache/jev/.

Pull requests

One topic per pull request, with tests.
Describe what changed, which spec items it touches, how you validated it, and any new entry in docs/known_unknowns.md.
Add a line to the Unreleased section of CHANGELOG.md for anything a user would notice.

Reporting problems

Use the issue templates. New issues get an automatic first triage (.gitea/workflows/issue_triage.yml): the title and text are sent to the TypeSafe API, which suggests kind and area labels, notes missing information, and flags personal data, vendor file contents or credentials so they can be removed. A maintainer checks every label. For a wrong or unexpected result, attach the run_manifest.json of the run and the exact command; it records every version, option and input checksum. Please do not attach vendor files or any genetic data of real people. For security issues see SECURITY.md.

Questions and feedback that do not fit an issue are welcome at [email protected].

5.9 KiB Raw Blame History