Skip to main content

Versioning and migration

CadFlow 0.1.0 is Alpha. Public APIs are documented and testable, but breaking signature or schema changes may still occur before a stable release.

Pin and record​

Pin the exact Python package and native library build used to create deliverables. Record:

  • CadFlow version and source revision;
  • platform and native backend capability data;
  • input resource hashes;
  • parameter values and unit system;
  • Model JSON or domain JSON schema version;
  • terminal result IDs and output artifact hashes.

Upgrade sequence​

  1. Regenerate or check the API reference against the candidate runtime.
  2. Review added, removed, and changed signatures in static/api-reference-manifest.json.
  3. Import existing serialized artifacts without executing them.
  4. Migrate versioned schemas through documented public functions.
  5. Replay in strict mode in an isolated environment.
  6. Compare terminal geometry, topology, dimensions, semantics, and artifacts.
  7. Update pins only after acceptance evidence passes.

Signature drift gate​

From the documentation repository, with a compatible CadFlow environment:

PYTHONPATH=../CadFlow/python python scripts/generate_api_reference.py --check

The check fails when a generated page, public import, signature, category, alias, or bilingual file set differs from the checked-in reference. Run the command without --check to regenerate after reviewing the runtime change.

Serialized schemas​

Model JSON, Scene packages, physical layers, and simulation models carry schema identity or version metadata. Never rewrite their JSON with ad hoc string replacement. Parse through the public importer, transform typed or structured data, export through the public serializer, and validate again.

Non-strict replay is a diagnostic and migration tool, not evidence that an artifact remains equivalent. Finish migration with strict replay and domain-specific comparison.

Deprecation handling​

When a public alias is deprecated, move call sites to the recommended canonical import before removing the old pin. Do not replace a public function with a private implementation import simply because both currently resolve to the same object.