SimurgArray/CONTRIBUTING.md

# 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

```bash
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

```bash
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

1. **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.
2. **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.
3. **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.
4. **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.
5. **Exact by default.** Default mode stays bit exact with the reference outputs. A cleaner numerical choice goes
   behind an explicit option.
6. **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.
7. **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.
8. **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:

```bash
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]**.