Stability and Versioning Policy¶

This page defines the intended stability contract for ONNX IR 1.x.

Semantic versioning¶

Starting with 1.0, ONNX IR follows semantic versioning:

  • MAJOR: breaking API or behavior changes

  • MINOR: backward-compatible feature additions

  • PATCH: backward-compatible fixes

API stability levels¶

Stable surface¶

The following are expected to remain backward-compatible within a major release:

  • Public top-level APIs documented in the docsite API reference.

  • Core model/graph/value/node mutation and traversal interfaces.

  • Serialization/deserialization entry points intended for users.

Evolving surface¶

The following may change more frequently and should be version-pinned by advanced users:

  • Experimental helpers not explicitly documented as stable.

  • Performance-oriented internals and private modules (names prefixed with _).

  • Emerging pass/helper utilities that are not yet designated stable.

Deprecation policy¶

When a stable API must change:

  1. It is first marked deprecated in documentation and/or code comments.

  2. A migration path is provided.

  3. Removal occurs in a later major release, except for urgent security reasons.

Behavior and correctness expectations¶

  • ONNX spec coverage and serialization correctness are prioritized over convenience.

  • Security-sensitive behavior (for example external tensor path containment) is fail-closed where applicable.

  • Performance improvements should not silently change public semantics.

What this means for adopters¶

  • Pin to <2.0 if you want 1.x compatibility.

  • Treat private modules as implementation details.

  • Follow release notes and migration docs before upgrading major versions.