“This article was updated on October 29th, 2024 to include five changelog versioning best practices”
A changelog is like a museum that shows the history and evolution of a product as it goes through changes, updates, and new releases. Changelogs help create a visual thread that follows the product’s progress for years after the initial version release.
But how are these changelogs sorted and labeled, and what do they mean for users and developers?
This article aims to outline the meaning of changelog versioning and semantic versioning, explain how they work and their purpose, and give a few examples of how SaaS companies use changelog versioning to keep users informed.
Table of Contents
- What Is Changelog Versioning?
- What Is Semantic Versioning?
- How Changelog Version Numbers Work
- What Are the Advantages of Using Semantic Versioning When Creating a Changelog?
- 5 Changelog Versioning Best Practices
- 5 Examples of SaaS Companies Appropriately Using Changelog Versioning
- AnnounceKit Provides an Interactive Changelog Tool for Seamless Product Updates
What Is Changelog Versioning?
A changelog is a file composed of a curated list of significant changes for each version of a project or software. The changes are chronologically recorded and labeled to allow users to follow the evolution of the product easily. This process is called changelog versioning.
Changelog versioning helps a SaaS company:
- Build a better product
- Value customer feedback; and
- Allow their team and users to keep track of updates
AnnounceKit allows developers and project managers to announce new product updates, release notes, and changelogs in an eye-catching way to keep your users actively updated and engaged. Powered by email notifications, user feedback, analytics, and user segmentation, AnnounceKit streamlines changelog versioning using widgets for optimal product rollout.
Quick Setup, Easy to Use, and Many Integrations
Manage your product announcements from a single place and easily distribute them
across multiple channels.
What Is Semantic Versioning?
Semantic versioning, or SemVer, is a parlance for changelog versioning. It is a way of numbering a software release. SemVer is widely used to encode software changes in a three-component number, instead of two. This standardization helps users and developers track whether changes are major, minor, or quick fixes. Instead of releasing a new version of a product for minor changes, semantic versioning allows developers to notify users of minor changes and patches.
Semantic versioning also allows developers to release updates without running into version lock — the inability to upgrade small aspects of a project without needing to release new versions of the entire thing.
SemVer specification rules that software must be declared as a public API. Public API, or Open API, refers to a publicly available application programming interface that provides multiple developers free access to a software application or web service.
Public APIs enable users to follow the progress of a SaaS product and track which minor feature requests and bug fixes have been addressed.
How Changelog Version Numbers Work
Semantic changelog versioning follows a three-part pattern expressed as X, Y, Z. X stands for major version changes, Y stands for minor changes, and Z stands for patches or bug fixes.
Major changes are backward incompatible. Minor changes and patches are backward compatible. This means that minor changes and patches can be applied to the older version, but major changes must be a newly released version.
Major Number
Major versions are considered new versions altogether, the number sequence must be changed to signify a break in the API. Breaking a change in the API will require the user to update the application on their side if they want to use the updated API. This is what we are referring to when we mention backward incompatibility.
Major version releases require a restart and reinstall, while minor changes and patches may only require a quick update. You might notice this happening when a new IOS comes out if you have an iPhone. The system has to shut down and restart to replace the operating system and avoid crashing while updating.
In the graphic above, the major number is 2. It denotes a significant architectural change that will cause a break in the API. When the major number is increased to signify a version update, the minor and patch numbers must be reset to 0.
For example, if the current version is 2.0.4 and a major version is released, the semantic changelog versioning will now be 3.0.0 because our new version has no current features or bug fixes.
Minor Number
Minor updates or feature changes to the major version are classified as Y in the X, Y, Z semantic versioning pattern. It represents the number of minor changes to the major version of the product.
These changes are backward compatible, meaning that these changes only make minor changes that do not break the API.
The minor number in the graphic above is 0. This tells us that there have been no new features or enhancements since major version number 2 (represented as X) was rolled out. If the minor number was incremented, the major number would stay the same, and the patch number would be reset to 0.
For example, if the semantic versioning is 2.0.4, and a minor update is released, the semantic versioning will change to 2.1.0, which means this is the second version with one feature change and no patches or bug fixes.
Patch Number
The final number, Z, stands for patch number. In the case of changelog versioning, patch updates may include the following:
- Bug fixes
- Security updates
- Temporary feature fixes
Any type of backward-compatible bug fixes will be noted as this integer. In our example, 2.0.4, the last number 4 stands for four patches or bug fixes in version 2 (X integer).
If there are more patches/bug fixes before version 2.1 or version 3 is released, then the semantic changelog versioning would change from 2.0.4 to 2.0.5. Patches should always be backward compatible. If they are not, it would require the release of a new major version.
How Many Numbers Change With Each Semantic Versioning Release?
There is generally only one number of changes per release. If you were to release four major changes and 12 new features, your changelog wouldn’t jump from 1.0.0 to 4.12.0. It would just jump to 2.0.0.
When a new major version is released, all numbers are set back to 0, whether any feature updates or patches are addressed.
What Are the Advantages of Using Semantic Versioning When Creating a Changelog?
SemVer is a remarkably simple system that parcels software changes into user-friendly terminology. Instead of logging lines and lines of information explaining changes, semantic versioning conveys them into manageable, bite-sized integers.
Other semantic versioning advantages include the following:
- Clear and concise history of changelog development
- Mechanistic codebase for computer understanding
- Expressive format that can be easily understood and identified by users and developers
Quick Setup, Easy to Use, and Many Integrations
Manage your product announcements from a single place and easily distribute them
across multiple channels.
5 Changelog Versioning Best Practices
So, how do you produce the best changelog with accurate changelog versioning? You follow these five changelog versioning best practices, of course.
#1: Date Each Release and Always Start With the Latest Version
Dates matter, and the order in which they are presented also matters. By providing a clear timeline, you can inform users about the frequency of updates while also establishing a sense of reliability within your changelog.
Consider your audience and their preferences when deciding the best way to format dates. For example, your customers based in the United States are most familiar with the MM-DD-YYYY date format. In contrast, users in other countries are more familiar with the DD-MM-YYYY format. So, how can you ensure the dates on your release make sense to your entire audience regardless of location?
Be consistent, offer clarity, and choose different format options that achieve this goal, such as:
- Long Format: Write the full date with the month spelled out, like “March 10th, 2025.”
- Short Format: Implement a shortened version of the date, such as “Mar 10th, 2025.”
- Numeric Format: Represent the date numerically, such as “03/10/2025” (month/day/year) or “10/03/2025” (day/month/year).
- ISO 8601 Format: Use the international standard with dates formatted as “YYYY-MM-DD,” which is clear and widely recognized.
If your user base is global, you may want to also include time zone information to avoid further confusion. Alternatively, you could use Coordinated Universal Time (UTC) as a standardized reference point.
#2: Categorize Changes
Tame the chaos that is sometimes found with unorganized changelogs by categorizing changes. If you’re consistently making updates, it’s a lot of information for users to take in. If you categorize those changes, you’ll add structure and help users quickly find relevant updates.
Avoid over-complicacy by having a few straightforward features that broadly reflect specific categories. For example, you could use tags to quickly signify the type of change being made, such as
- Added
- Changed
- Deprecated
- Removed
#3: Provide Links to Relevant Resources
Do the work and make it easy for your users by connecting the dots for them. This means including helpful links to additional resources, which might empower them to explore more information about additions or changes by actively engaging in your product.
By simply providing extra resources, you can greatly impact users’ product or feature adoption practices. You could even feature links to how-tos or activation points to activate that update.
#4: Provide Information About User Impact
When you make changes to your product, the first thing your users will want to know is how these changes affect them. If you fail to communicate end-user impact in your changelog, your inbox will be flooded with questions from concerned customers who want to know what’s up.
All changes have a purpose. Don’t hide your reasoning from your customers. Articulate the end-user impact to:
- Address potential concerns
- Foster user confidence in your project
- Strengthen the relationship between your product and users
- Show you want to produce the best product possible.
#5: Review and Update Regularly
One of the best changelog practices is accuracy and consistency. Practice makes perfect when it comes to changelog versioning and best practices. So continue to improve your changelog until it is just as user-friendly and optimized for success as your product.
By regularly reviewing your changelog, you can maintain an accurate roadmap of your product and feature as a reliable source of information. Our changelogs might be digital, but we are human. This practice will also help catch inaccuracies, encourage user feedback, and ensure your operations remain aligned with the evolution of your product.
5 Examples of SaaS Companies Appropriately Using Changelog Versioning
In the following examples, we will be using changelog updates to demonstrate how you can tell if an update is a major version, minor version, or patch.
#1: Spotify
The above example displays the version update for Spotify introduced on July 27th, 2022. Two features were added, which were the unlinking support feature and the example partner website feature. Since these two changes were minor feature updates, only the minor version number was increased.
So, with these changes, the changelog versioning changes from 1.5.0 to 1.6.0.
#2: Zoom
This example exhibits a recent changelog versioning update for Zoom. The semantic versioning is 5.17.7. This informs us that Spotify is on its 5th version and has had 17 feature updates and seven bug fixes.
The recorded changes updated the patch number to resolve an issue regarding audio recording with Zoom clips.
The number that is in parentheses (31859) is an optional addition to a semantic versioning number. It symbolizes the build metadata associated with the update.
#3: Contentsquare
The above example demonstrates two minor version feature releases for Contentsquare.
The updated changelog versioning signifies that two separate feature releases were added. One is for saving hashes to avoid duplicate sends (13.82.0) and the other is for automatically masking credit card numbers (13.83.0).
By observing the semantic versioning numbers, we know that the updated product is on its 13th major version, which has had 82 minor version updates and zero patches for the current version.
#4: Box
This example is a rather detailed changelog for Box, a cloud-based content management development and marketing firm. Box enables developers to use APIs to connect to other systems and centralized metadata.
The numbers (#870), (#874), and (#869) are links referring to pull and feature requests (11bf5d2, 55a80b, and 22384ab) on the open-source developer platform GitHub. While Box is announcing its 5th minor update on its 3rd version, they’re also linking the pull requests that are related to the updates.
This informs other software developers and users that this pull request has been addressed in the update.
Your audience wants their feedback to be addressed and heard.
Feature requests allow your users to submit valuable feedback for suggested changes to your product. AnnounceKit makes it easy for users to submit requests and developers to view and manage them.
Along with a dedicated feature request and changelog platform, AnnounceKit’s changelog software allows you to:
- Create customizable public changelog pages
- Set privacy options for internal use
- Serve changelog under your domain
- Collect feedback and reactions to your posts
- Announce rich media content
#5: GoTo Meeting
In this example, GoTo Meeting is announcing a feature that allows remote control for attendees. We can tell that this was a minor feature update and not a new version release by noticing that the patch number is 0. If this were a major version release and not a minor version release, the changelog versioning would be 5.0.0 or 6.0.0 instead of 5.46.0.
AnnounceKit Provides an Interactive Changelog Tool for Seamless Product Updates
As a software developer, changelog and semantic versioning is simple, but for your users, it may not always be. What may be a clear, concise project roadmap to you is just a set number for your clients and consumers.
How can you present your changelog versioning in a way that clearly announces exciting updates and rollouts?
AnnounceKit provides an interactive changelog tool that allows users, developers, and project managers to create a clear roadmap and follow the evolution of a product with changelog versioning. With our software, you can empower your changelogs by linking feature requests that have been fulfilled by the updates.
Our pages are customizable, so whatever changelog versioning format you prefer, you can integrate it with Announcekit. Our changelog app will enable you to interact with audience engagements with your changelog. 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.
![Great email to introduce product updates [+Real examples]](https://announcekit.app/blog/wp-content/uploads/2021/05/great-email-768x461.jpeg)
