Skip to main content

Developer home

This page routes Limen contribution work to the matching maintenance path before code, docs, or release metadata changes.

For cross-product Vaquum process and organization-wide norms, see the external Vaquum Developer Docs. Limen release and versioning contracts live in this repository.

Prerequisites​

  • a Limen repository checkout
  • the task's authoritative issue and repository workflow instructions

Read this first​

Before opening or updating a Limen PR:

  • read the relevant Limen page for the task
  • check the repo PR template and satisfy every applicable item
  • update docs, changelog, tests, and version metadata when the change requires it

Route by task​

TaskRead this nextWhy
changing docs structure, navigation, or page rolesDocumentation System ContractDefines the docs architecture, page types, site model, and rewrite rules.
updating reducer behaviorPruning StrategiesDefines reducer semantics, YAML shape, testing, and failure modes.
updating or adding public functions, classes, or modulesWriting DocstringsDefines Limen's docstring expectations and the repo's current house style.
adding a new foundational experiment templateContributing Foundational SFDsCovers research expectations, file ownership, and review criteria for foundational SFDs.
preparing a release or checking release automationMaking a ReleaseDefines the local evidence required before Limen release publication.
changing release or publish-path controlsRelease PolicyDefines the publish-path gates, model authority boundary, release deliverables, and version-reuse rules.
changing package metadata, artifacts, extras, or packaging gatesPackagingDefines the wheel/sdist, dependency, reproducibility, and provenance contract.
deciding how to bump the versionSemantic VersioningDefines the Limen-local version surfaces and bump rules.
assessing recorded known riskTechnical DebtTracks accepted debt, trigger conditions, and candidate remedies.

Contributor workflow​

  1. Start with data: confirm whether the task uses bundled YAML templates, direct HistoricalData, or an external OHLC-compatible source.
  2. Confirm the signal layer: read the relevant Indicators, Features, Transforms, and Scalers pages before changing prep.
  3. Confirm prep semantics: preserve split-first preparation, CCO behavior, strict-mode null handling, and train-fitted transformations.
  4. Confirm the target: read Targets and make sure fitting happens only on the training split when the target learns thresholds.
  5. Confirm hyperparameters: route search-space changes through the manifest/YAML params surface unless the task is Python-extension-only.
  6. Train through the current run surface: prefer YAML plus CLI for operator-facing work, and direct UEL only for Python extension or test work.
  7. Benchmark outcomes with Log, Benchmark, and Backtest before claiming the change improves research behavior.
  8. Make code, docs, tests, changelog, and version changes together when they belong together.
  9. Review the full GitHub diff before requesting review.
  10. Confirm the PR template items are true, not just checked.

Canonical bootstrap:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Canonical validation paths:

python -m pytest
python -m tests.run
python -m build
python scripts/package_audit.py
ruff check .

python -m tests.run delegates to pytest collection and adds the CI runtime profile artifact. It is not a separate curated test list.

Docs-site validation:

cd docs-site
npm ci
npm run check

Limen does not define a tox, nox, or Makefile contract; these direct commands are the authoritative local workflow.

Test runtime budget​

  • PR Validation publishes a test-runtime-profile artifact from python -m coverage run -m tests.run, which uses pytest collection.
  • PR Checks Runtime enforces the suite ceiling committed in tests/runtime_budget.json.
  • Update tests/runtime_budget.json only when recent green main CI runs show a real new baseline, and keep that evidence in the linked issue or PR.
  • Do not raise the budget to absorb avoidable slow tests; every pytest test executed through tests/run.py is timed automatically.

Scope notes​

  • /docs is the canonical public docs layer.
  • /docs/Developer is the canonical Limen contributor layer.
  • package READMEs under /limen are orientation pages, not the main contributor process docs.
  • release and versioning policy lives in this repository; shared Vaquum docs are background only.