Chris Dzombak

Choosing a Version Number for a CocoaPod with Updated Dependencies

Semantic Versioning generally provides a clear rule for incrementing a library’s version number:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

But it fails to explicitly cover one case which commonly arises with CocoaPods:

A pod can declare dependencies on other pods. If a new release of a pod requires an updated version of one of its dependencies, how does semantic versioning take that updated dependency into account?

We can only integrate a single version of a given pod into our application; thus all pods we use which depend on pod X must depend on the same version of pod X. This means that a pod’s declared dependencies can affect the entire application.

Updating a dependency to a backwards-incompatible version could break other pods, and the application itself, at integration time. From a semantic versioning standpoint, this limitation effectively makes a pod’s declared dependencies part of the pod’s public API.

Therefore, when choosing a version number for a new release of a CocoaPod, one must take any dependency updates into account: if any dependency has been updated to a new minor version, the pod’s new version number must at least be a new minor version. And if any dependency has been updated to a new major version, the pod’s new version number must at least be a new major version.

Some Examples

Pod A used to require pod B version 1.0.2; it now requires Pod B version 1.0.3.

This may be considered a new patch version of Pod A.

Pod A used to require pod B version 2.1.0; it now requires Pod B version 3.0.0.

This must be considered a new major version of Pod A.

Pod A used to require pod B version 3.1.1; it now requires Pod B version 3.2.0.

This must not be considered a new patch version of Pod A.


As always, I welcome discussion and feedback; I’m @cdzombak on Twitter.