Version numbers in TYPO3 and extensions: Your shortcut to better planning

What is Semantic Versioning (SemVer)?

Version numbers according to the MAJOR.MINOR.PATCH scheme are no coincidence, but follow a clear system: Semantic Versioning, or SemVer for short. This concept helps developers, integrators and even users to understand at a glance what an update entails.

Here is the basic idea:

• MAJOR (e.g. 13.x.x): The large number on the far left indicates that this is a version with profound changes. You must expect adjustments here, as older features may no longer be compatible.
• MINOR (e.g. x.4.x): This number means that new features have been added, but they are backwards compatible. Everything continues to run as usual, just with a few additional options.
• PATCH (e.g. x.x.5): The last part of the version number stands for bug fixes or security updates. These versions repair errors without changing the functionality - these are the updates that you can install without much thought.

Practical, isn't it? So with SemVer you can not only understand if an update is critical, but also what kind of changes you can expect. Especially in the TYPO3 world, where the core and extensions often develop independently of each other, this is worth its weight in gold.

But SemVer doesn't just have advantages - we'll come to that later. For now, let's take a look at how this affects TYPO3 and the extensions in detail.

---

TYPO3 core: What the version numbers tell you

Let's take a look at the TYPO3 core. The version number here follows the classic MAJOR.MINOR.PATCH scheme, and each number has a clear meaning. The good thing about this is that you can roughly estimate what to expect before the update - without having to look at the changelog.

MAJOR: The left-hand number - big changes

The first number in the version number, e.g. 13 in 13.4.2, shows you that a new major version is coming. This often means major changes, new features and sometimes also that old functions (deprecations) have been removed. So if you are updating from TYPO3 12 to 13, you should check whether your setup remains compatible - be it with extensions, templates or the server configuration.

Example: When upgrading from TYPO3 12 to 13, many legacy features were removed and modern features were introduced. Without preparation, the update may surprise you and your website.

MINOR: The middle number - new possibilities

The second number, e.g. 4 in 13.4.2, stands for a downward-compatible extension. New functions or improvements are added here without affecting existing projects.

Example: In TYPO3 13.3, the new backend module for Site Settings was added. You don't have to adapt anything, but you can use the function directly if you want.

PATCH: The right number - small repairs

The last number, e.g. 2 in 13.4.2, is like a safety net. This is about bug fixes, security updates or minimal optimizations. You can usually install these updates directly, as they neither add new features nor change existing functions.

Example: A patch update often fixes minor problems, such as incorrect behavior in the backend or security vulnerabilities in the frontend.

So if you understand the version number in TYPO3 core, you can plan much better:

• A MAJOR update? Make sure you check what's changing beforehand.
• A MINOR update? Try out cool new features if you want.
• A PATCH update? Just do it - it only provides more stability.

This information alone will save you time and nerves, especially with large projects. In the next section, we'll look at how this works with extensions - because it's just as exciting there.

---

Extensions and version numbers

With extensions, it's similar to the TYPO3 core: here, too, you can quickly recognize what you're getting into based on the version number - at least if the developers adhere to semantic versioning. The numbers tell you whether you can install the update immediately or whether you should be more careful.

MAJOR: The left-hand number - watch out for big jumps

If the first number changes, e.g. from 1.x.x to 2.x.x, this means: Beware, fundamental things may have changed here. The extension may have been adapted to such an extent that older TYPO3 versions or other dependencies are no longer supported. Incompatible changes are the rule here.

Example: An extension that was optimized for PHP 8.2 in version 2.0.0 may suddenly no longer work on older servers. Without a prior check, you run the risk of it blocking your system.

MINOR: The middle number - new features

A jump in the second number, e.g. from 1.2.0 to 1.3.0, means new features or improvements. These updates are usually backwards compatible, so your existing installation will continue to work without any problems.

Example: A developer adds the ability to manage multiple recipient lists to a newsletter extension in version 1.3.0. You can use the new function immediately, but you don't have to.

PATCH: The right number - import safely

The last number, e.g. the change from 1.3.0 to 1.3.1, stands for bug fixes or security updates, as with TYPO3 core. There's no need to be afraid of surprises here - these updates don't change anything in terms of functionality or features.

Example: A bug that caused a form not to be saved correctly is fixed in version 1.3.1. The update makes the extension more stable and secure.

What should you look out for?

Not all extension developers adhere strictly to semantic versioning. A supposedly harmless MINOR update can suddenly lead to problems if, for example, functions are removed when they should actually remain. It is therefore worth taking a quick look at the release notes or changelog before updating - at least for larger projects.

Conclusion for extensions

Version numbers are like an early warning system. If you understand the logic behind them, you can make a better decision as to whether you should apply an update straight away or play it safe. And if something goes wrong, at least you'll know why. In the next section, we look at how developers, integrators and users alike can benefit from this knowledge.

---

Benefits for developers, integrators and users

Semantic versioning isn't just a technical standard - it's also a real game changer when it comes to making working with TYPO3 more efficient and less stressful. Here is an overview of how everyone involved benefits from it:

Developers: Clear communication and less chaos

SemVer is a tool for developers to bring order to their releases. Each number in the version number clearly communicates what has changed. This not only makes collaboration within the team easier, but also helps users to correctly assess updates.

Example: If a developer upgrades an extension from 2.3.0 to 3.0.0, everyone knows that something big is coming and that old functions may have been removed. This avoids misunderstandings and unnecessary support requests.

Integrators: Plan with confidence and make better decisions

As an integrator, you are often the one who tests and installs updates. With semantic versioning, you can see at a glance how critical an update is for your project. This saves time and helps to avoid nasty surprises.

Example: You can see that an extension is jumping from 1.5.2 to 1.6.0. You can install the update with peace of mind, because only new features are being added - no changes that could jeopardize your setup.

Users: Clear communication and stability

Even if users do not install updates themselves, they benefit indirectly from semantic versioning. With stable LTS versions such as 13.4.x, only the patch numbers change, which means that only bugs are fixed and security gaps are closed. For users, this means no surprises and a stable, familiar system.

Example: You work as an editor in the TYPO3 backend and hear that a patch update from 13.4.2 to 13.4.3 has been installed. Without any big announcements, you can be sure that your usual functions will remain the same, just with fewer bugs in the background.

Common advantage: less risk, more efficiency

In the end, everyone benefits when semantic versioning is used consistently. Developers save themselves the chaos of support requests, integrators can plan updates in a more targeted manner and users understand better what they can expect from new versions. With a little knowledge about the logic of version numbers, dealing with TYPO3 becomes much more relaxed - no matter which side you're on.

In the next section, we'll take a look at the pitfalls and how you can avoid typical misunderstandings.

---

Typical pitfalls and misunderstandings

Semantic versioning is a powerful tool, but as with any system, there are pitfalls. If you rely on every version number always following the SemVer rules exactly, misunderstandings can quickly arise - especially if developers or integrators don't work properly.

1. When MINOR updates do cause problems

In theory, MINOR updates should only add new functions without changing existing ones. In practice, however, it happens that functions are unintentionally changed or even removed. This can lead to unexpected problems, especially with complex integrations.

Example: An extension jumps from 1.3.0 to 1.4.0. You were actually only expecting additional features, but suddenly important parts of your website no longer work because a dependency is no longer supported.

Solution: Check the changelog before every update, especially for larger projects.

2. MAJOR updates without clear communication

A jump in the MAJOR version signals incompatible changes. However, not all developers document exactly which functions have been removed or changed. As a result, integrators or developers are faced with surprises when they install the update.

Example: An extension is updated from 2.3.1 to 3.0.0 and important configuration options have been removed. Without warning, you now have to look for an alternative solution - which costs time and nerves.

Solution: Check the release notes and compatibility information carefully before MAJOR updates.

3. Extensions that do not adhere to SemVer

Not every extension developer adheres strictly to Semantic Versioning. A supposedly harmless PATCH update can suddenly introduce new functions or changes that actually belong in a MINOR or MAJOR update.

Example: An update from 1.2.2 to 1.2.3 introduces a new feature that is not compatible with your setup. You are surprised because you only expected a minor bug fix.

Solution: Pay attention to the developer's reputation, especially with less well-known extensions, and consult the changelog in case of problems.

4. Misunderstandings with pre-release versions

Versions such as 1.0.0-alpha.1 or 2.3.0-beta.2 can cause confusion. They are explicitly not intended for productive use, often contain bugs and can change significantly before the final release. Nevertheless, such versions are sometimes inadvertently used in live systems.

Example: You install a beta version of an extension and wonder about missing functions or crashes. Only later do you realize that the final version has not yet been released.

Solution: Only use pre-release versions in development environments - never on live systems.

5. Confusion between MAJOR and MINOR with TYPO3 LTS

With LTS versions such as 13.4.x, some expect MINOR updates to be included. However, only the PATCH number is relevant for stable LTS versions. A misunderstanding here can lead to you unnecessarily delaying updates, even though they only fix bugs.

Example: An integrator decides not to update from 13.4.2 to 13.4.3 because he fears a major change. In fact, he could have installed it without any problems, as it is only a bug fix.

Solution: Always keep LTS versions in mind: MINOR remains constant, PATCH only ensures stability and security.

Conclusion: Stay vigilant

Semantic versioning is a reliable system - as long as everyone involved uses it properly. A little caution and checking release notes will help you avoid misunderstandings and get the full benefit of the version numbers. In the next section, I will give you practical tips on how you can make even better use of version numbers.

---

Practical tips for using version numbers

Version numbers are more than just numbers - they are a useful tool if you know how to use them. Here are a few simple and effective tips to help you get the most out of semantic versioning:

1. Always keep an eye on the changelog

Version numbers give you an initial orientation, but the changelog is your safeguard. Especially with MAJOR and MINOR updates, it's worth taking a quick look at what exactly has been changed. This will save you any surprises and show you whether you need to make any special adjustments.

Practical tip: Always keep the changelog for your most important extensions and TYPO3 versions to hand. Many developers link to it directly on GitHub or in the TER description.

2. Don't install all updates immediately

Especially with MAJOR updates, it can make sense to wait a few weeks. The first PATCH versions often fix minor problems that arise after the major release. If you are patient, you will save yourself potential stress.

Practical tip: When an update has just been released, keep an eye on the community - integrators are often quick to discuss potential problems.

3. Classify pre-release versions correctly

Alpha, beta and RC versions (release candidates) are intended for testing, not for live systems. Only use them if you want to try out new functions or prepare your setup. These versions have no place in productive operation.

Practical tip: Create a separate test environment to evaluate new features or simulate updates before they go live.

4. Keep an eye on SemVer deviations

Not all extensions adhere strictly to Semantic Versioning. Especially with lesser-known or older extensions, MINOR or PATCH updates may contain changes that you would not have expected.

Practical tip: Pay attention to the reputation of the extension developers and test updates in a secure environment before applying them to large projects.

5. Use TYPO3 LTS versions strategically

With stable LTS versions, you only need to focus on the PATCH numbers. MINOR remains constant, so you only get bug fixes and security updates. Use this knowledge to carry out updates quickly and easily.

Practical tip: Always keep your TYPO3 LTS version up to date - security updates in particular are often overlooked, even though they are installed quickly.

6. Create documentation for your team

If you work for larger projects or teams, it's worth creating a small internal guideline for updates and version numbers. This way, everyone has a clear orientation and knows how to assess version jumps.

Practical tip: Create a checklist that defines how MAJOR, MINOR and PATCH updates should be handled - including tests and release processes.

7. Involve the community

The TYPO3 community is a great place to share updates and experiences. You can often get early feedback on new versions here before you have to get involved yourself.

Practical tip: Check the TYPO3 forum, Slack or Forge regularly to stay informed about potential pitfalls.

Conclusion: less stress, more control

If you use version numbers consciously and combine them with the right tools and routines, you can approach updates much more safely and efficiently. Stay curious, test updates in a targeted manner and use the advantages of semantic versioning for clean planning - your TYPO3 system will thank you for it.

---

Conclusion

Version numbers are more than just a technical detail - they're like a compass to help you find your way through TYPO3 updates and extensions. With a little knowledge of semantic versioning, you can see at a glance what you're getting yourself into: Are adjustments necessary? Can I install the update directly? Are there new functions that will take me further?

For developers, integrators and even users, this system offers a clear structure and creates trust. Developers communicate better, integrators plan more reliably and users can rely on stability. Of course, there are also pitfalls - such as extensions that do not adhere to the rules. But with a keen eye and the right preparation, many problems can be avoided.

If you use version numbers consciously, you save time, nerves and, in the best case, even money. Whether it's the TYPO3 core or extensions: the numbers are your shortcut to better planning and stress-free work with TYPO3.

What are your experiences with semantic versioning? Have you ever experienced surprising updates or developed useful routines? Feel free to share your thoughts and tips in the comments!

Back