Clarifications to version policy

docs/docs/version-policy.md

@@ -1,49 +1,82 @@
 # 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
-
+2. Icechunk Python Library Version
+3. Icechunk Rust Crate Version
 
 ## Icechunk Spec
 
-The spec will advance with any revisions as defined in the [Spec document](./spec.md).
+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](./spec.md).
+
+## 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](#data-format-specification-compatibility) 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.
 
-## `icechunk` Python Library
+* **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.
 
-Versions of this library are identified by a triplet of integers with the form `<major>.<minor>.<patch>`
+  Users should always feel safe upgrading to a the latest patch release.
 
-### Library Version
+Note that this versioning scheme is not consistent with [Semantic Versioning](https://semver.org/).
+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.
 
-#### Major Versions
+A better model for our versioning scheme is [Intended Effort Versioning](https://jacobtomlinson.dev/effver/), or "EffVer".
+The guiding principle off EffVer is to categorize releases based on the *expected effort required to upgrade to that release*.
 
-The `icechunk` Python library will change when there is an on-disk incompatible change in the Icechunk Spec.
+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.
 
-##### Reading
+## Data format specification compatibility
 
-The latest release of `icechunk` Python will always be able to read data written against any version of the Icechunk Spec.
+The Icechunk library is an implementation of a file format standard defined separately -- see the [Icechunk specification](./spec.md).
 
-##### Writing
+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.
 
-`icechunk` Python will be able to, at minimum, write to the last major version of the Icechunk Spec. This means that `icechunk` Python 2 can write to Icechunk Spec version 1 format. `icechunk` Python 3 will be able write to Icechunk Spec 2, but not Icechunk Spec 1.
+**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](https://earthmover.io/blog/evolving-our-tensor-storage-engine-a-preview-of-icechunk-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`.
 
-###### Forward Compatibility
+### Reading
 
-`icechunk` Python will **not** implement forward compatible reading and writing. `icechunk` Python version 1.x.x will not be able to read or write the Icechunk 2 format.
+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.
 
-#### Minor Versions
+### Writing
 
-Minor releases will require at most minor effort from users to update their code. Minor versions will increment with new features, significant bug fixes, or for small changes in python library api compatibility.
+`icechunk` Python will be able to, at minimum, write to the last major version of the Icechunk Spec.
 
-#### Patch Versions
+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.
 
-Patch releases will require no effort on the part of users of `icechunk` Python. They will contain bugfixes or documentation improvements.
+### 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
+## Icechunk Rust Crate
 
-No explicit versioning scheme followed here.
+No explicit versioning scheme is followed by the icechunk rust crate.