Skip to content

Home / version-policy

Icechunk Version Policy#

There are three versions referred to in this document:

  1. Icechunk Spec Version
  2. Icechunk Python Library Version
  3. Icechunk Rust Crate Version

Icechunk Spec#

The Icechunk format specification ("icechunk spec") versions are identified by a single integer.

The spec version will increment if and only if there is an on-disk incompatible change in the Icechunk Spec, as defined by the spec document.

Icechunk Python Library#

Versions of this library are identified by a triplet of integers with the form <major>.<minor>.<patch>, for example 1.1.12. A release of icechunk-python is associated with a new version identifier. That new identifier is generated by incrementing exactly one of the components of the previous version identifier by 1. When incrementing the major component of the version identifier, the minor and patch components is reset to 0. When incrementing the minor component, the patch component is reset to 0.

Releases are classified by the library changes contained in that release. This classification determines which component of the version identifier is incremented on release.

  • major releases (for example, 1.1.12 -> 2.0.0) are for changes that will require extensive adaptation efforts from many users and downstream projects. For example, breaking changes to widely-used user-facing APIs should only be applied in a major release.

Users and downstream projects should carefully consider the impact of a major release before adopting it. In advance of a major release, developers should communicate the scope of the upcoming changes, and help users prepare for them.

IMPORTANT: Any backwards-incompatible change to the Icechunk format specification is always treated as a significant change for users, and so will therefore always be accompanied by a major release. For more details see the section on data format specification compatibility below.

  • minor releases (for example, 3.0.0 -> 3.1.0) are for changes that do not require significant effort from most users or downstream downstream projects to respond to. API changes are possible in minor releases if the burden on users imposed by those changes is sufficiently small.

For example, a recently released API may need fixes or refinements that are breaking, but low impact due to the recency of the feature. Such API changes are permitted in a minor release.

Minor releases are safe for most users and downstream projects to adopt.

  • patch releases (for example, 3.1.0 -> 3.1.1) are for changes that contain no breaking or behaviour changes for downstream projects or users. Examples of changes suitable for a patch release are bugfixes and documentation improvements.

Users should always feel safe upgrading to a the latest patch release.

Note that this versioning scheme is not consistent with Semantic Versioning. Contrary to SemVer, the Icechunk library may release breaking changes in minor releases, or even patch releases under exceptional circumstances. But we strive to avoid doing so.

A better model for our versioning scheme is Intended Effort Versioning, or "EffVer". The guiding principle off EffVer is to categorize releases based on the expected effort required to upgrade to that release.

Icechunk developers endeavour to make changes as smooth as possible for users. This means making backwards-compatible changes wherever possible. When a backwards-incompatible change is necessary, users will be notified well in advance, e.g. via informative deprecation warnings.

Data format specification compatibility#

The Icechunk library is an implementation of a file format standard defined separately -- see the Icechunk specification.

If an existing Icechunk format version changes, or a new version of the Icechunk format is released, then the Icechunk library will generally require changes. We choose to treat these changes as significant to justify a new major version of the icechunk python library.

Therefore any update to the Icechunk format specification version will be accompanied by a major release of the icechunk python library.

For example, when the new Icechunk version 2 format specification is first supported, it will be via a new major icechunk-python release, with a version updated from 1.x.y to 2.0.0.

Reading#

The latest release of icechunk Python will make best efforts to always be able to read data written against any previous version of the Icechunk Spec.

Writing#

icechunk Python will be able to, at minimum, write to the last major version of the Icechunk Spec.

For example, this means that icechunk Python version 2 can write to Icechunk Spec version 1 format, but while icechunk Python 3 will be able write to Icechunk Spec version 2, is it not guaranteed to be able to write to Icechunk Spec version 1.

Forward Compatibility#

icechunk Python will not implement forward compatible reading and writing. For example icechunk Python version 1.x.x will not be able to read or write data using the Icechunk format 2 (or later).

Icechunk Rust Crate#

No explicit versioning scheme is followed by the icechunk rust crate.