86 lines
4.7 KiB
Markdown
86 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
## 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]**.
|