Development workflow

Use this page as a lightweight checklist for code changes.

Before changing code

  1. Identify the owner package.

  2. Check existing tests for the behavior.

  3. Decide whether docs or changelog entries are needed.

  4. Keep generated files out of the patch unless the source file is meant to be generated.

Where changes usually belong

Change type

Start here

App setup, Flask app, database initialization

ivoryos/app.py, ivoryos/config.py, ivoryos/server.py

Runtime state

ivoryos/runtime/state.py

Direct-control routes

ivoryos/routes/control/

Workflow design routes

ivoryos/routes/design/

Execution routes and queue entry points

ivoryos/routes/execute/

Workflow execution

ivoryos/runtime/

Workflow models and generated script behavior

ivoryos/script/

Type conversion and interface schema parsing

ivoryos/parsers/

Dynamic form behavior

ivoryos/forms/dynamic_forms.py

Database models

ivoryos/models/

Optional services

ivoryos/services/

Optimizer adapters

ivoryos/optimizer/

If a change crosses several rows, document the boundary in the merge request or add a short developer page.

Changelog and docs

Update CHANGELOG.md when a change affects users, integrators, public behavior, dependency requirements, or release-visible bugs.

Update docs when a change affects:

  • UI workflows;

  • ivoryos.run(...) options;

  • input type behavior;

  • generated proxy behavior;

  • route behavior;

  • optimizer configuration;

  • runtime behavior such as queue, pause, stop, retry, or cleanup.

Use Docs organization to decide where a page belongs.

Pull request checklist

  • The behavior is covered by a focused unit or integration test where practical.

  • Existing tests pass, or any failure is explained.

  • The docs build passes when docs changed.

  • User-facing behavior is mentioned in CHANGELOG.md.

  • Generated build output is not committed.

  • Runtime data under ivoryos_data/ is not committed.

  • New public behavior has an obvious place in the user, integrator, or developer docs.

Generated docs pages

The suite README pages under docs/source/integrators/ are generated during the Sphinx build from upstream repositories:

  • client-api.md

  • mcp-server.md

  • plugins.md

Do not edit those generated files directly. Change their source repositories or update external_readmes in docs/source/conf.py.