Yuval Tassa
c54f1fe380
PiperOrigin-RevId: 869102767 Change-Id: I8b01b9343289d4ad7d15bcc3634a28e661308a90
76 lines
2.9 KiB
Markdown
76 lines
2.9 KiB
Markdown
# 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](https://semver.org/)
|
||
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](https://mujoco.readthedocs.io/en/stable/XMLreference.html) and the
|
||
related
|
||
[mjSpec](https://mujoco.readthedocs.io/en/stable/programming/modeledit.html)
|
||
API. Furthermore, the numerical properties of physics state integration mean
|
||
that despite being deterministic, numerical reproducibility across versions is
|
||
almost guaranteed to
|
||
[not hold](https://mujoco.readthedocs.io/en/stable/computation/index.html#reproducibility).
|
||
|
||
## 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](https://mujoco.readthedocs.io/en/stable/changelog.html), 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](https://mujoco.readthedocs.io/en/stable/computation/index.html#reproducibility),
|
||
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](https://mujoco.readthedocs.io/en/stable/changelog.html#version-3-0-0-october-18-2023)'s
|
||
introduction of the JAX-based
|
||
[MJX](https://mujoco.readthedocs.io/en/stable/mjx.html) branch. Additionally:
|
||
|
||
- The function
|
||
[`const char* mj_versionString()`](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-versionstring)
|
||
returns the version in the form of a string, for example `"3.2.7"`.
|
||
- The function
|
||
[`int mj_version()`](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-version)
|
||
returns an integer equal to the version digits concatenated,
|
||
for example for "3.2.7" we'd have `mjVERSION = 327`.
|