Understanding PSPDFKit Version Numbering

On Apple platforms, PSPDFKit 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 PSPDFKit for Web and PSPDFKit for Android.

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)

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

In these PSPDFKit updates, we increase our primary version number. For example, in 2023, PSPDFKit 12 was updated to PSPDFKit 13, which has the full version number 13.0.0. Therefore, the 13 in (for example) PSPDFKit 13.4.1 for iOS communicates that this release came out in PSPDFKit’s thirteenth year. PSPDFKit’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 PSPDFKit 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 PSPDFKit 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, PSPDFKit uses an ANNUAL.RELEASE.PATCH version numbering system. For example, consider the version number 13.4.1:

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