Skip to main content

Semantic Versioning in Mobile Development

This post was not planned. Technically I was supposed to talk about testing in Flutter but, after the week I've spent as an architect in my current job fighting with dependencies I am seeing how even big companies or software products are ignoring when publishing packages and dependencies something as important as version semantics but I felt forced to talk about version semantics. That is, more specifically about best practices when versioning our packages and mobile dependencies in Flutter, Android and iOS. Let's get to the point.

Flutter, Android and Apple logos about semantic versions

Semantic Versioning

As developers, knowing the version semantics is very important as it helps us to decide the version number of our next version of our application, package or dependency. 

An important fact that sometimes distorts the use of versioning semantics is that when publishing applications, this can often be slightly distorted. As long as the version number is higher than the previous one (something that the apps market force us to do), the rest is a matter of marketing. 

But when we work with APIs, packages or dependencies, things become stricter if we don't want to make a mess of developers and they reject our product or end up angry.

Official documentation

Harvard University in 1997 published a paper entitled Key words for use in RFCs to Indicate Requirement Levels which discussed this issue. Years later, someone posted on the web an interpretation of this document which I am attaching here. The most important part or summary for me is the following:

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 backward compatible manner.
  • PATCH version when you make backward compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

What does it mean?

This means that if we have only corrected things that were not where we wanted them to be or simply failed before, we should release a patch version. If, in addition or on the contrary, we find minor enhancements or improvements, we should release a minor version. Finally, if our changes are very large and/or disruptive to the way things used to work, we should release a major version.

Wrong examples

Disruptive changes in minor versions...

Release notes of RXPermissions dependencies of Android in Github

Disruptive changes in patch versions. Also it's funny because they thought it should be but trust me, it was a breaking change...

Release notes of RX Kotlin dependency in Github

At least they are not ashamed to admit it. Breaking changes in minor versions.

Release notes of Apollo Client iOS dependency in Github

And here...
Release notes of Apollo Client iOS dependency in Github


You can see that there are many mobile packages who are still unaware of this. I hope this help all of us to be aligned in the future about this topic. Forgive me this week for being so grumpy about this issue, but I am concerned that we are ignoring good practices and recommendations about semantic versioning. 

See you in other posts!


© 2020 Mobile Dev Hub