Question about versioning and stable releases

[johnbent]

Looking at NEWS.md, I see there are release notes for 1.11.1 but no notes for 1.11.2. Will release notes be coming out?

Also, is there anywhere documented what the versioning scheme is? Is 11 the minor version and 2 is the minor version? Is 1.11.2 the latest stable version? If we are looking to use libfabric in a production environment, how are we to know which version we should use?

Thanks for libfabric! FYI: we are using it for CORTX .

[shefty]

The 1.11.2 release was created from the v1.11.x branch, so the NEWS.md has been updated there. See:

https://github.com/ofiwg/libfabric/blob/v1.11.x/NEWS.md

It's actually somewhat surprising the the v1.11.1 release notes are already in master.

What usually happens is that release notes from the stable branches (v1.10.x, v1.11.x, etc.) are copied back into the master branch NEWS.md file prior to a new major release (e.g. v1.12.0). After each major release, a new stable branch is created (v1.12.x).

Libfabric uses a major.minor.micro versioning scheme at the release level:

https://www.usenix.org/legacy/publications/library/proceedings/als00/2000papers/papers/full_papers/browndavid/browndavid_html/index.html

and the libtool versioning at the library level:

https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

The 1 indicates the major version. This will only change to 2 if a change is made which breaks binary applications and could require source code changes. There are no plans of changing the major version.

The minor version (e.g. 11) indicates that the source code saw significant changes from the prior minor version. In some cases, new APIs were introduced or data structures were extended. We require that applications compiled against minor version X continue to work with version X+1. We also require that applications coded to minor version X be able to recompile against version X+1 without any source changes, and that the compiled code work.

What is not guaranteed is that an application coded and/or compiled against minor version X must work with version X-1. An application can achieve this, but would need to code for this through build and run time checks. For example, the minor version is defined in fabric.h and could be used to select certain code paths. The version is also available via a run time call.

The micro version indicates that the library contains only bug fixes. So, v1.x.y would contain only bug fixes to release v1.x.y-1. (v1.11.2 has bug fixes to v1.11.1, which has bug fixes to v1.11.0).

To make matters somewhat confusing, because we never change the major number, we refer to new major releases as changes to the miner number. Likewise, changes to the micro number are referred to as minor (or bugfix) releases.

Typically, the best option to use in production would be the latest stable release (e.g. v1.11.2). Because major releases (e.g. v1.12.0) may contain significant changes from the last stable release, I would perform more validation before migrating between major releases. As for development, see the fabric.7 man page for notable ABI/API changes which occurred between versions. You would need to decide based on your application which version of the API for the source code to target, so that the app can run with older versions of libfabric (e.g. shipped by a distro).