Internal Applications: When Semantic Versioning Doesn't Make Sense

Semantic Versioning (or SemVer) is great for libraries and open source applications. It allows development teams to communicate to user and downstream developers the scope of changes in a release. One of the most important indicators in versioning is backwards compatibility (BC). SemVer makes any BC break clear. Web services and public APIs are another excellent use case for SemVer.

As much as I love semantic versioning for public projects, I am not convinced about using it for internal projects.

Libraries, be they internal or publicly released should follow the semantic version spec. Not only does this encourage reuse and sharing of libraries, it also displays good manners towards your fellow developers. Internal API endpoints should also comply with SemVer, but versioning end points should only expose major.minor in the version string. Again this will help maintain good relations with other devs.

End users of your application probably won't care if you drop jQuery in favour of straight JS, swap Apache for nginx or even if you upgrade to PHP 7/Python 3.x. Some users will care if you move a button. They won't care that the underlying data model and classes remain unchanged and so this is only a patch release. In the mind of those users, the button move is a BC break, because you changed their UI. At the end of the day, users don't care about version numbers, they care about features and bug fixes.

Regardless of the versioning system used, changes should be documented in a changelog. The changelog shouldn't just be a list of git commits streamed into a text file. This changelog should be something a non technical user can get their head around. This allows all stakeholders to clearly see the incremental improvement in the system.

In my mind SemVer breaks down when it comes to these types of (web) applications. Without a doubt any of the external integration points of the app should use semantic versioning. However the actual app versioning should just increment. I recommend using date based version numbering, such as 201512010 for the first release on 1 December 2015. The next release on that same day, if required, would be 201512011 and so on. If you release many times per day then you might want to consider a 2 or 3 digit counter component.

The components that make up your application such as the libraries, docker base images, ansible playbooks and so on should be using SemVer. Your build and test infrastructure should be able to create reproducible builds of the full stack if you reference specific versions or dependencies.

Instead of conditioning end users to understand semantic versioning, energy should be expended on teaching users to understand continuous delivery and deployment. The app is going to grow and evolve, tagging a release should be something a script can do. It shouldn't need 5 people in the tea room trying to work out if a feature can go in or not because it might be considered a BC break.

When building an application, get the code written and have people using it. If they're not happy, continue to iterate.

Actually I would recommend

Paul Keeble wrote:

Actually I would recommend just using the build numbers that come out of your continuous integration tool. Ultimately all you really need is a hook back to the code that produced that release so you can recreate it if needed, the more direct the better.

Semvar is about technical consumers, people who need to know things have changed. Alternatively its used as a marketing tool, Windows 10 verses 8. When doping continuously updated websites however it has no practical use so its actually easier to drop it and stop putting a manual decision into the build pipeline, instead moving to a number that is 100% automated.

Added Mon, 2016-01-25 20:49

RE: Actually I would recommend

Dave wrote:

I agree you shouldn't need a human to decide the version number for many web apps. The build id as the version number is a good idea. I know at least one build system I use generates randomised build ids. That makes it difficult to work back through tags chronologically. That's where the idea for the date based version numbers came from.

Added Tue, 2016-01-26 00:58

RE: Actually I would recommend

Anonymous wrote:

I use date based version number and tag the repo with it. On greater than 0 occasions I've reset the build numbers on the build system (don't ask).

Added Fri, 2016-01-29 15:06

Typo found

Francis Kim wrote:

Typo in 'ningx' ;)

Added Sat, 2016-01-30 15:36

RE: Typo found

Dave wrote:

@Francis, thanks. I don't know how I missed that. I've fixed it now.

Added Sat, 2016-01-30 22:34

Using the build numbers from

small business bookkeeping wrote:

Using the build numbers from the continuous integration tool makes sense. I like your blog Dave, its practical and useful.

Added Mon, 2016-08-29 20:01

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Lines and paragraphs break automatically.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <p> <div> <blockquote> <pre>

More information about formatting options

By submitting this form, you accept the Mollom privacy policy.