Contributing

Thank you for your help. All contributions are under the Contributor Licence Agreement (CONTRIBUTOR-LICENSE.md in the repository root).

Set up

make install          # uv sync --all-packages (+ pnpm install once apps/ exist)
make help             # every developer entry point

Command	What it does
make test	Runs the default test suite (all tests, but not the Docker, cloud and end-to-end tests)
make test-fast	Runs only the unit tests. It does not run the slow MCMC tests
make lint	Runs ruff, the ruff format check and the import-linter contracts
make typecheck	Runs mypy on each package that has type checks
make conformance	Runs the conformance corpus at size tiny (FIXTURE=e33 for one fixture)
make docs-serve	Shows this site and loads it again when a page changes
make docs-build	Makes the generated reference pages again and builds the site in strict mode
make docs-test	Runs all the documentation snippets and the checks of the docs
make dev	Runs the whole stack locally without Docker (Local, without Docker)
make docker-build / make compose-up	Builds the images / runs the compose stack (Docker Compose)
make release-check	Does a check of version consistency, the changelog entry, plan files (there must be none), pinned images and current third-party notices
make notices	Makes THIRD-PARTY-NOTICES.md again after a change to uv.lock or pnpm-lock.yaml (Licensing)

make install installs all workspace packages. This includes mapi-jax with the CPU build of JAX (v0.15), mapi-sklearn with the gbm extra (LightGBM and CatBoost, v0.14) and pymc-extras (a dependency of mapi-plugin-ts, v0.13). Two extras are for installs outside the workspace: the cuda12 extra of mapi-jax (only the mapi/base-dl image uses it) and the pathfinder extra of mapi-pymc (pymc-extras for the Pathfinder engine). Do not add torch or tensorflow. The build of mapi/base-dl fails if they are in it (Container images).

Package	Where	What it holds
mapi-jax (v0.15)	packages/sdk-jax	The dl.* models and the step dl.embed on JAX, Flax and Optax
mapi-plugin-causal (v0.13)	plugins/causal	causal.impact, causal.synthetic_control and causal.did

The control plane and the supervisor of the runner must not import mapi_jax, jax, flax or optax. make lint makes sure of this rule.

Branching model

We use git flow with two permanent branches, main and develop.

gitGraph
    commit id: "v0.1.0" tag: "v0.1.0"
    branch develop
    checkout develop
    commit id: "integration"
    branch feat/m1-runner
    checkout feat/m1-runner
    commit id: "feat(runner): …"
    commit id: "test(runner): …"
    checkout develop
    merge feat/m1-runner
    branch feat/m1-docs
    checkout feat/m1-docs
    commit id: "docs: …"
    checkout develop
    merge feat/m1-docs
    checkout main
    merge develop tag: "v0.2.0"

Branch	Purpose
main	Releases only. We merge each milestone from develop and tag it vX.Y.Z. Nobody commits to main directly.
develop	Integration. We merge feature branches here with --no-ff.
feat/<milestone>-<topic>	One unit of work. Make the branch from the latest develop.

git checkout -B feat/m1-my-change develop
# ... small, logical commits ...
make fmt lint typecheck test

Do not rebase or rewrite develop or main. Keep changes to shared files small, and only add to them. The shared files are the root pyproject.toml, the Makefile, uv.lock and CI. Tell about these changes in your pull request.

Writing style

Write all text for users in ASD-STE100 Simplified Technical English. This includes the documentation, the text in the web app, and the messages that the server sends for the app to show. The rules are in Writing style.

Commit messages

Use Conventional commits, with the package as the scope:

feat(sdk): replay context tails at each step's input stage
fix(server): reject score requests whose horizon exceeds the fit
docs: add the porting guide
test(conformance): add the e24 filter fixture
chore: bump ruff

Code style

• Use Python 3.12 and ruff (line length 100). Use type hints in all code. Use mypy strict for the core packages.
• Tests are in tests/ in each package. PyMC fits in tests use very small settings (tune: 50–150, draws: 50–150, chains: 2). If a test takes more than about ten seconds, mark it slow.
• Write short docstrings (Google style). The contract tests are the executable documentation.
• mapi_spec must not import numpy, xarray or pandas. The server must not import plugin code or array code. make lint makes sure of the two rules.

Documentation

The site uses MkDocs Material. mkdocs.yml is at the repository root, and the pages are in docs/.

• The tests run all Python examples. The examples are in docs/snippets/*.py. Pages include them with --8<-- "file.py:section". conformance/tests/test_docs_snippets.py
• Platform examples run against a live stack. make e2e runs the client, HTTP and remote-CLI walkthroughs (docs/snippets/client_tour.py, http_tour.sh, cli_remote.sh). The default suite runs the local CLI walkthrough (cli_local.sh) in conformance/tests/test_docs_platform.py. Shell snippets use the same section markers.
• Scripts make the reference pages. scripts/gen_docs_catalog.py writes the pages for the steps, models, plot recipes, spec schema and error codes. scripts/gen_docs_reference.py writes the CLI reference, the server settings and a copy of apps/web/openapi.json. scripts/gen_docs_platform.py writes the permissions, the environment variables and the tables of the observability page. The three scripts write into docs/reference/generated/, which git ignores. An MkDocs hook runs them before each build. make docs-catalog runs them. To change a generated page, change the code or the script, not the output.
• New MAPI_* variables go into the configuration reference (docs/operations/configuration.md). A test looks for these variables in the source tree.

• Screenshots are in docs/assets/screenshots/. Each screenshot must be 300 KB or less, and a page must use it. make docs-screenshots captures them again from a stack that runs and has seed data. Other targets capture one set each:

  • from a make dev stack: docs-screenshots-admin and docs-screenshots-science (the science tutorials, with the datasets of Science data);
  • from the web app in mock mode: docs-screenshots-guided, docs-screenshots-integrations, docs-screenshots-tutorials, docs-screenshots-explorers and docs-screenshots-workflows.

  The configuration reference lists the variables that these scripts read. - The cookbook documents are tested. conformance/tests/test_docs_v05.py makes sure that each docs/snippets/cookbook_*.yaml is a valid workflow. It also makes sure that the documents of the six M5 recipes (cookbook_sci_*.yaml and cookbook_bayes_workflow_audit.yaml) are the same as their gallery templates. If you change one of these templates, change its document too. - make docs-build must pass (mkdocs build --strict, with anchor validation). - Write for two types of readers. An analyst wants to know what a feature does for them. A data scientist wants to know exactly how it works.