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:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- 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.