Skip to content

VERSIONING.md

Latest commit

 

History

History
75 lines (58 loc) · 2.94 KB

VERSIONING.md

File metadata and controls

75 lines (58 loc) · 2.94 KB

MuJoCo Versioning

MuJoCo uses custom semantic versioning from 3.5.0 onwards, see below.

The problem with Semantic Versioning

The common definition of traditional Semantic Versioning is

1. MAJOR:  breaking changes
2. MINOR:  new features
3. PATCH:  bug fixes

With strict adherence to this definition, most MuJoCo releases are MAJOR. This is because MuJoCo has a very large API surface, especially when considering MJCF and the related mjSpec API. Furthermore, the numerical properties of physics state integration mean that despite being deterministic, numerical reproducibility across versions is almost guaranteed to not hold.

From 3.5.0 – semantic versioning

From 3.5.0 onwards MuJoCo uses well-defined versioning with the following semantics.

MuJoCo versioning semantics

1. SUPERMAJOR:      breaking changes and/or significant new features
2. MAJOR:           breaking changes, possibly new features
3. MINOR_OR_PATCH:  new features or bug fixes

MINOR_OR_PATCH guarantees API backward compatibility, but may or may not introduce new features; to find out, read the changelog, which will detail the nature of the changes. The changelog will also detail pure ABI-breaking changes, for example removing an unused attribute from a public struct. Such changes are considered MINOR. As explained here, numerical reproducibility is never guaranteed.

Additionally:

  • mj_versionString() works as before, returning e.g. "4.2.1".

  • mj_version() works as before, returning an integer. The corresponding header constant mjVERSION_HEADER is calculated from the components as:

    mjVERSION = (SUPERMAJOR * 1e6) + (MAJOR * 1e3) + MINOR_OR_PATCH

    For example, 4.2.1 would be 4002001.

Prior to 3.5.0 – no semantics

Until 3.5.0, versioning was a sequence of increasing numbers with no well-defined semantic, with the exception of major versions introducing significant new features, like 3.0.0's introduction of the JAX-based MJX branch. Additionally:

  • The function const char* mj_versionString() returns the version in the form of a string, for example "3.2.7".
  • The function int mj_version() returns an integer equal to the version digits concatenated, for example for "3.2.7" we'd have mjVERSION = 327.