Changelog Versioning: How Semantic Version Numbers Work (With 5 SaaS Examples)

Changelog versioning is the practice of labeling every entry in a changelog with a version number, so users can see what changed and how big the change was. Semantic versioning (SemVer) is the widely used format: a three-part number such as 2.0.4, where the first number marks major releases, the second marks new features, and the third marks patches. A quick look at the number tells a user whether an update will break anything.

This guide explains what changelog versioning is, how semantic version numbers work, why they help, and how five SaaS companies use them in their public changelogs.

Table of Contents

• What Is Changelog Versioning?
• What Is Semantic Versioning?
• How Do Changelog Version Numbers Work?
• What Are the Advantages of Semantic Versioning in a Changelog?
• 5 SaaS Changelog Versioning Examples
• AnnounceKit: An Interactive Changelog Tool for Versioned Product Updates

What Is Changelog Versioning?

A changelog is a curated list of the significant changes in each version of a project or piece of software. The changes are recorded in chronological order and labeled with a version number, so users can follow the evolution of the product. Labeling entries this way is called changelog versioning.

For teams handling SaaS product management, changelog versioning helps them:

• Build a better product
• Show that customer feedback is valued
• Let the team and users keep track of updates

If you are starting from scratch, read our guide on how to keep a changelog and browse these changelog template examples.

AnnounceKit lets developers and product managers announce product updates, release notes, and changelogs in an eye-catching way that keeps users updated and engaged. With email notifications, user feedback, analytics, and user segmentation, AnnounceKit streamlines changelog versioning through widgets built for product rollouts.

Quick Setup, Easy to Use, and Many Integrations

Manage your product announcements from a single place and easily distribute them
across multiple channels.

Go to Website

What Is Semantic Versioning?

Semantic versioning, or SemVer, is the standard way to number a software release. It encodes changes in a three-part number instead of two. The format lets users and developers see at a glance whether a change is major, minor, or a quick fix. Instead of shipping a whole new product version for small changes, developers can notify users of minor changes and patches.

Semantic versioning also lets developers release updates without running into version lock, the inability to upgrade one small part of a project without releasing a new version of the whole thing.

The SemVer specification requires that the software declare a public API. A public API, or open API, is a publicly available application programming interface that gives developers free access to a software application or web service.

Public APIs let users follow the progress of a SaaS product and track which minor feature requests and bug fixes have been addressed.

How Do Changelog Version Numbers Work?

Semantic changelog versioning follows a three-part pattern written as X.Y.Z. X is the major version, Y is the minor version, and Z is the patch number for bug fixes.

Major changes are backward incompatible. Minor changes and patches are backward compatible. In practice, minor changes and patches can be applied to the older version, while a major change ships as a new release.

Major Number: Breaking Changes

A major version is treated as a new version altogether. The first number changes to signal a break in the API. A breaking API change means users must update the application on their side if they want to use the new API. This is what backward incompatibility means.

Major releases usually require a restart and reinstall, while minor changes and patches may only need a quick update. You see this on an iPhone when a new iOS version comes out: the system shuts down and restarts to replace the operating system without crashing mid-update.

In the graphic above, the major number is 2. It denotes a significant architectural change that breaks the API. When the major number increases, the minor and patch numbers reset to 0. For example, if the current version is 2.0.4 and a major version is released, the version becomes 3.0.0, because the new version has no feature updates or bug fixes yet.

Minor Number: New Features

Minor updates and feature changes to the major version are the Y in the X.Y.Z pattern. The number counts the minor changes made to the current major version.

These changes are backward compatible. They add or improve features without breaking the API.

The minor number in the graphic above is 0. This tells us there have been no new features or enhancements since major version 2 was rolled out. When the minor number increases, the major number stays the same and the patch number resets to 0. For example, if the version is 2.0.4 and a minor update is released, the version becomes 2.1.0: the second major version, with one feature change and no patches yet.

Patch Number: Bug Fixes

The final number, Z, is the patch number. In changelog versioning, patch updates may include:

• Bug fixes
• Security updates
• Temporary feature fixes

Any backward-compatible bug fix increments this number. In our example, 2.0.4, the last number means four patches have shipped for version 2.

If more patches ship before version 2.1 or version 3 is released, the version moves from 2.0.4 to 2.0.5. Patches should always be backward compatible. If a fix is not, it requires a new major version.

How Many Numbers Change With Each Semantic Versioning Release?

Only one number changes per release. If you shipped four major changes and 12 new features at once, your changelog would not jump from 1.0.0 to 4.12.0. It would move to 2.0.0.

When a new major version is released, the minor and patch numbers reset to 0, no matter how many feature updates or patches it contains.

What Are the Advantages of Semantic Versioning in a Changelog?

SemVer is a simple system that packages software changes into user-friendly terms. Instead of logging lines of text to explain each change, semantic versioning conveys the scope of a release in three small integers.

Other semantic versioning advantages include:

• A clear, concise history of the changelog's development
• A mechanical format that computers can parse
• An expressive format that users and developers can read and identify at a glance

The same numbering works for an internal and an external changelog, so engineers and customers can refer to the same release.

Quick Setup, Easy to Use, and Many Integrations

Manage your product announcements from a single place and easily distribute them
across multiple channels.

Go to Website

5 SaaS Changelog Versioning Examples

The following changelog updates show how to tell whether an update is a major version, a minor version, or a patch.

1. Spotify: A Minor Version Bump From 1.5.0 to 1.6.0

The example above shows a Spotify version update released on July 27th, 2022. Two features were added: unlinking support and an example partner website. Because both were minor feature updates, only the minor number increased. The changelog version moved from 1.5.0 to 1.6.0.

2. Zoom: A Patch Release at 5.17.7

This example shows a recent changelog update for Zoom. The version is 5.17.7, which tells us Zoom is on its 5th major version and has shipped 17 feature updates and seven bug fixes since then.

The recorded change bumped the patch number to resolve an issue with audio recording in Zoom clips.

The number in parentheses (31859) is an optional addition to a semantic version number. It represents the build metadata attached to the update.

3. Contentsquare: Two Minor Releases, 13.82.0 and 13.83.0

The example above shows two minor feature releases for Contentsquare.

The version numbers tell us two separate features shipped: saving hashes to avoid duplicate sends (13.82.0) and automatically masking credit card numbers (13.83.0).

Reading the numbers, we know the product is on its 13th major version, which has had 82 minor updates and zero patches on the current minor version.

4. Box: Version 3.5 With Linked Pull Requests

This example is a detailed changelog from Box, a cloud-based content management company. Box lets developers use APIs to connect to other systems and centralized metadata.

The numbers (#870), (#874), and (#869) link to pull requests and feature requests (11bf5d2, 55a80b, and 22384ab) on GitHub. While Box announces the 5th minor update of its 3rd major version, it also links the pull requests related to each update.

This tells other developers and users that a specific request has been addressed in the release.

Your audience wants their feedback heard and addressed.

Feature requests let users submit suggested changes to your product. AnnounceKit's feature request software makes it easy for users to submit requests and for developers to view and manage them.

Along with a dedicated feature request platform, AnnounceKit's changelog software lets you:

• Create customizable public changelog pages
• Set privacy options for internal use
• Serve your changelog under your own domain
• Collect feedback and reactions on your posts
• Announce rich media content, including video release notes

5. GoTo Meeting: A Minor Release at 5.46.0

In this example, GoTo Meeting announces a feature that lets attendees take remote control. The patch number is 0, which tells us this was a minor feature update rather than a patch. If it had been a major release, the version would read 5.0.0 or 6.0.0 instead of 5.46.0.

AnnounceKit: An Interactive Changelog Tool for Versioned Product Updates

To a software developer, changelog and semantic versioning are simple. To your users, they may not be. What reads as a clear project roadmap to you is just a number to your customers.

How can you present changelog versioning in a way that clearly announces new updates and rollouts?

AnnounceKit provides an interactive changelog tool that lets users, developers, and product managers create a clear roadmap and follow the evolution of a product through changelog versioning. You can strengthen each changelog entry by linking the feature requests fulfilled by the update.

The pages are customizable, so whatever changelog versioning format you prefer, it works with AnnounceKit. The changelog app also lets you see how your audience engages with each post. Start for free, or book a demo today.

Quick Setup, Easy to Use, and Many Integrations

Manage your product announcements from a single place and easily distribute them
across multiple channels.

Go to Website