Understanding Nutrient version numbering

On Apple platforms, Nutrient uses a version numbering system where PRIMARY.SECONDARY.TERTIARY (e.g. 13.4.1) should be interpreted as ANNUAL.RELEASE.PATCH. This guide explains this numbering system. Note that it doesn’t apply to our other products, such as Nutrient Web SDK Nutrient Android SDK.

Software releases can use various systems for numbering releases, such as semantic versioning (MAJOR.MINOR.PATCH) or year-based versioning (YEAR.RELEASE.PATCH).

Apple moves its platforms forward on a consistent annual cycle. It releases significant updates to its operating systems and developer tools each year, typically in the fall. In these updates, the primary version number is incremented. For example in 2023, Xcode 14 was updated to Xcode 15, iOS 16 was updated to iOS 17, and so on. This annual cadence has a strong impact on software development on Apple platforms.

Types of releases

Annual release (X.0.0)

Nutrient iOS, Mac Catalyst, and visionOS SDKs use annual version numbers in sync with Apple’s updates. Every fall, alongside Apple’s major updates, we release a Nutrient update adding support for the new versions of Xcode and the operating systems.

In these Nutrient updates, we increase our primary version number. For example, in 2023, Nutrient iOS SDK 12 was updated to Nutrient iOS SDK 13, which has the full version number 13.0.0. Therefore, the 13 in (for example) Nutrient iOS SDK 13.4.1 communicates that this release came out in Nutrient’s thirteenth year. Nutrient’s first release was way back in 2011!

This is not semantic versioning. This annual increment of the primary number doesn’t imply that this release is a large, riskier update or includes breaking changes. In fact, we’d like our customers to move to the new Xcode version to switch the base SDK to Apple’s latest version, as this helps transition smoothly to the new operating system and reduces our testing burden. Therefore, we try to make sure annual releases are easy updates.

Release (X.Y.0)

In an update that isn’t an annual release (see above) or a patch release (see below), we increment the secondary number. These releases are built from our main development branch, and they may include features, fixes for reported issues, and improvements to our documentation and sample code.

Patch release (X.Y.Z)

Patch releases include only targeted fixes, and usually only for issues we know are causing problems for our customers. In general, updating to a patch release is very safe.

We increment the tertiary number for patch releases, which is consistent with many other versioning numbering systems. For example, in the version number 13.4.1, the 1 indicates it’s a patch release that came out after version 13.4.0.

Breaking changes

Patch releases never make breaking changes.

We may occasionally introduce breaking changes in other releases (i.e. updates where either the primary or secondary number is incremented). That said, we try to avoid this for annual releases when possible. See our changelog for details, as we’ll always draw attention to these changes with the API badge and include suggestions for how to migrate, linking to a migration guide when more detail is needed.

To keep Nutrient as up to date as possible, use the dependency rule “branch” set to “master.” We don’t recommend using “up to next major version” because we increment the primary version number to support new Xcode and operating system versions, so these updates increase rather than decrease compatibility.

If you want to update Nutrient manually, we recommend using “up to next minor version.” We don’t recommend using “exact version,” because you’ll miss out on patch releases, which resolve issues and, as mentioned above, are generally very safe.

Summary

On Apple platforms, Nutrient uses an ANNUAL.RELEASE.PATCH version numbering system. For example, consider the version number 13.4.1:

13 — This release came out in Nutrient’s thirteenth year.
4 — This is the fourth release since 13.0.0.
1 — This is the first patch release since 13.4.0.