Somite welcomes focused bug fixes, documentation improvements, operator contracts, and workflow capabilities. Start with the user or scientific outcome; implementation details should follow from that outcome.
- Search existing issues and discussions.
- Open an issue before a large feature, graph-schema change, execution-target change, or operator-contract change.
- Never include credentials, private datasets, unpublished paper content, or machine-specific absolute paths.
- Keep claims evidence-bound. A graph edit, successful compilation, representative validation, and production execution are different outcomes.
Use the checked-in Pixi environment for development:
pixi run install
pixi run devOr use Node.js from .nvmrc directly:
npm ci
npm run devTo exercise the production path, run pixi run setup once and then
pixi run start. Starting the app reuses the built bundle.
The repository is one npm workspace: web/ owns browser interaction,
runner/ owns local I/O and processes, packages/workflow/ owns graph and
workflow semantics, packages/mcp-runtime/ owns the shared MCP boundary, and
mcp/pixi/ plus mcp/nextflow/ expose the two external toolchains. Local
graphs, uploads, evidence, benchmark profiles, and generated tool environments
live under .somite/ or output/ and must not be committed.
Linux x64 is the verified development and execution target. Contributions may retain portable seams, but other hosts are not release-gated yet.
- Keep one production path and delete obsolete code before adding abstraction.
- Put graph semantics, validation, compilation, and identity in
@somite/workflow; keep browser interaction inweb/and host/process I/O inrunner/. - Runtime-validate every persisted, network, catalog, paper, and Agent value. TypeScript types alone are not a trust boundary.
- Add tests at the narrowest useful Interface. Add a spawned-runner or browser test when behavior crosses Modules.
- Preserve graph identity, operator revisions, provenance, atomic writes, and fail-closed behavior.
- Update the README, relevant design documentation, and
CHANGELOG.mdwhen public behavior changes.
Run the full gate before requesting review:
npm ci
npm run check
npm run smoke:browser
npm run benchmark:quick
npm audit --audit-level=moderate
git diff --checkIn the pull request, list exact commands and manual checks. If a check is unavailable, state that directly and explain why.
The browser smoke uses a system Chrome or Chromium against the built production
bundle. Set SOMITE_BROWSER_PATH for a nonstandard executable location.
Release-affecting changes also require pixi run smoke on Linux x64. This is a
slower networked gate because it resolves and executes the real
pinned Pixi and Nextflow environment.
Performance changes must start with the relevant benchmark:quick receipt and
an outcome-preserving profile. Use profile:cpu or profile:heap for the exact
case, then compare a same-host candidate receipt. Do not use hosted-runner,
live-paper, or cross-machine wall times as a speed claim. The complete contract
and the slower release lane are in docs/benchmarks.md.
If a pull request intentionally changes that contract or either dependency
lock, ask a maintainer to apply benchmark-series-reset; CI verifies that a
passing new series is actually required rather than silently waiving a
comparable regression.
Packaging changes also require npm run proof:source after committing. That
task installs, builds, starts, and shuts down an archive of HEAD; it
intentionally ignores uncommitted files.
Release tags must be annotated, and their commit must already be reachable from
origin/main. The release workflow records both the tag-object identity and
resolved commit during verification, then checks both identities again
immediately before publishing. Never move, replace, or force-push a release
tag; correct a release with a new version and a new annotated tag.
By submitting a contribution, you agree that it is licensed under the Apache License 2.0.