Contributing to Sense Core

This page is a short contributor-facing summary of the current workflow. The authoritative internal guidance lives in sense-core/AGENTS.md; if this page and AGENTS.md ever differ, follow AGENTS.md.

Before You Ship

  • Use the torch conda environment for local validation.

  • Run unit tests with conda run -n torch s6 test.

  • Update the matching docs when you change user-visible or developer-relevant behavior.

  • Keep changes focused and avoid mixing unrelated behavior and docs updates.

What Needs Documentation

Update sense-core/docs/, sense-core/README.md, or sense-core/AGENTS.md when you change:

  • CLI commands, flags, defaults, examples, or command behavior

  • configuration schemas, defaults, or loading behavior

  • pipeline architecture, context schema, export payloads, or GUI bindings

  • dataset formats, training flows, deployment/export flows, or runbooks

  • developer workflows, setup steps, testing instructions, or contribution guidance

If a code change does not require a docs update, verify the existing docs still match the implementation before finishing.

Testing

The project uses s6 test as the unit-test entrypoint. Run it from the sense-core directory inside the torch environment:

conda run -n torch s6 test

For a single test, pass the dotted test path to s6 test:

conda run -n torch s6 test s6.utils.test_sync_controller.TestSyncControllerClientInit.test_init_no_trailing_slash

Commit Messages

Use Conventional Commits:

<type>(<scope>): <short description>

Preferred types are feat, fix, docs, style, refactor, perf, test, and chore. Keep the summary imperative and sentence case, and add a short body when the rationale matters.

Docstrings

For public Python APIs, use NumPy-style docstrings so Sphinx and Napoleon can render them consistently. Keep summaries short, document shapes and units when they matter, and prefer fully qualified cross-references for public symbols.

Common docstring rules:

  • Start with a concise summary sentence.

  • Add Parameters, Returns, Yields, and Raises sections where relevant.

  • Use Attributes or one-line property docstrings for public data fields.

  • Prefer present tense and active voice.

  • Keep examples short and focused.

Docs Build

The docs live under sense-core/docs/ and build with Sphinx. After changing docs or docstrings, regenerate the API reference and build the site:

cd sense-core
python scripts/generate_docs_api_reference.py
sphinx-build -W --keep-going -b html docs docs/_build/html

The generated site is written to sense-core/docs/_build/html.