TYPO3 Deprecation Policy

TYPO3 is one of the most stable, secure, and reliable open-source content management systems on the market. It powers highly sophisticated websites of companies such as Sony, Airbus, Carlsberg, and United Internet, to name a few. Enterprises of this size and reach require a reliable system with a clear and predictable upgrade path. Significant changes to the underlying system powering a website or web application are not acceptable if they break functionality. These “breaking changes” could be architectural, or result from the introduction of new technologies and methods.

Does this mean that TYPO3 core developers shouldn’t make changes to keep the content management system stable and upgrade-safe? Of course not!

On the other side of the coin, web technologies evolve at an incredible speed. New PHP (the primary programming language used for TYPO3) versions are released, developers release new and better libraries that TYPO3 uses as third-party components, and other libraries get decommissioned. TYPO3 must keep apace with these changes to stay ahead of its competitors.

Whenever a new technology replaces an existing solution, however, it poses a risk of breaking the old functionality. So, how do we handle the balance between stability and keeping up to date?

TYPO3 is known as an enterprise content management system, and it truly deserves this reputation. The system has been stable and robust for many years, and we introduced long-term support releases with TYPO3 version 4.5 LTS in 2011.

So-called “long-term support” releases mark the last version of a specific TYPO3 series. Let’s take TYPO3 v12 as an example. The first version 12.0 was released on 4 October 2022 as a sprint release. For more than nine months (the development period), we released successive versions— e.g., version 12.1 in December 2022 and version 12.2 in February 2023. The last version of the v12 series was TYPO3 version 12.4.0, released on 25 April 2023. This version automatically became an LTS-version (known as TYPO3 v12 LTS).

LTS releases receive maintenance and regular bug fixes for 1.5 years, and security updates (priority bug fixes) for another 1.5 years after that. This policy is our promise that when you build a website using an LTS-version, you can be sure that the core system is supported and maintained for free, at least three years after its release. These versions are called maintenance, bugfix, and security releases and are easily recognizable by the increased last number of their versions: v12.4.1, v12.4.2, v12.4.3, etc.

The following illustration shows the TYPO3 v9 and v10 release cycle:

On top of the free three-year maintenance and security support, TYPO3 GmbH offers vendor support for TYPO3, which makes for a total of six years of support for the open-source content management system. Read more about the extended long-term support plans (ELTS).

Given that the TYPO3 release cycle contains an LTS-release every 1.5 years, you could even skip a version and upgrade a TYPO3 instance from one LTS-version to another two versions later. For example, you could upgrade from version 10 LTS to 12 LTS. We try to make upgrades as smooth as possible and take the “skip-one-version” approach into account.

Let’s have a closer look at what this means for TYPO3 integrators and developers from a technical perspective.

As a modern web application, TYPO3 is built on top of a stack of underlying technologies. We clearly define the requirements for each LTS-version and stick to them throughout the lifetime of the version.

Typical examples for this promise are:

• PHP version and PHP settings
• Database engines and versions (e.g. MySQL, MariaDB, PostgreSQL, etc.)
• Web servers and versions

That said, we aim to support newer versions of these components when practical. Let’s say a new version of a database server comes out months after the first TYPO3 LTS release. We can make adjustments to support the new version, but our promise is not to break the platform requirements specified earlier—in this case, an older version of the database server.

This policy gives TYPO3 integrators and administrators the confidence to deploy bugfix and security releases (e.g., update from version 12.4.8 to 12.4.9) without worrying about the platform.

I mentioned “breaking changes” above. You may ask: how do TYPO3 developers keep the core state of the art by introducing new techniques and libraries while avoiding breaking changes when someone updates from one version to the next?

The TYPO3 core offers many modern APIs which enable extension developers to access, manipulate, and extend the core system’s basic functionality. If these interfaces changed from one version to the next, extensions would break too, and the entire system could fall apart. This would be a disaster for an enterprise content management system!

Here’s where TYPO3’s deprecation policy comes into play. By strictly following this policy, we define exactly what can change and when. As a result, core and extension developers understand what can change, and integrators know what to expect when we release a new TYPO3 version.

There are only a few exceptions when core developers are allowed to ignore this policy:

• Security issues
• Dependency updates
• Managed migrations
• Faulty system behavior

Let’s have a closer look at each of these exceptions.

The first exception is security issues. We take security very seriously, and vulnerabilities need to be fixed, no matter what. No compromise. If a security fix could be breaking change, we clearly and unambiguously communicate this in the security bulletin and release notes.

Another exception is a dependency update. This applies when one of the libraries used by the TYPO3 core needs to be updated. To keep a system stable and secure, we have to update all TYPO3 core components, including libraries maintained by third-party developers and vendors. If developers stop supporting an outdated version of their library, they force us to update the library used by the TYPO3 core to a maintained version. We call this process a dependency update.

A managed migration occurs when the Upgrade Wizard handles a breaking change between two sprint releases. Typical examples are a new TCA setting or a new database field. Although these updates might cause breaking changes, TYPO3’s Upgrade Wizard takes care of a smooth and faultless migration.

One more special case should be mentioned in this context, although it occurs very rarely. If a feature is or becomes faulty and does not work as it’s meant to, it may be fixed or adjusted. Depending on each use case and our interpretation of the feature’s previous behavior, some users might experience a breaking change. In these cases, we carefully assess the fix/adjustment impact and weigh the pros and cons.

When we introduce a breaking change into the TYPO3 Core, we mark the corresponding component as deprecated. This component could be a function or parameter, for example, that we want to remove from the codebase. The deprecation policy states that this component must remain intact in the current major release. However, core developers may remove the element in the next major version.

Let’s look at a simple example: a function named “hello()” that is part of TYPO3 v12 becomes outdated. Extension developers can and should use a better alternative to achieve the same result. Thus, a decision is made to remove the function from the TYPO3 core. First, the function “hello()” is marked as deprecated in, for example, TYPO3 version 12.0, but existing extensions that access this function remain working as before. From this point on, extension developers have plenty of time to update their extension code and switch to the alternative. The deprecation policy ensures that “hello()” will continue to work for the time being. We will not remove the function from the core until TYPO3 v13.

Breaking changes include architectural changes, new libraries that replace existing components, and modifications to PHP classes, properties, and methods. They can not be introduced when someone updates a TYPO3 version to the next bugfix release, e.g., version 12.4.8 to version 12.4.9.

You may ask how extension developers know when they need to update their code due to deprecation and—just as important—how TYPO3 integrators and site administrators know what could break when they plan an update to the next major version. Don’t worry: we have you covered! As pointed out above, breaking changes are marked as “deprecated” before we modify the code. The deprecation triggers an entry in the deprecation log file whenever TYPO3 executes the component. Please see the TYPO3 documentation for further details.

Once enabled, you find the log file in the “log/” directory of your TYPO3 instance (the exact path may vary depending on your setup and configuration). TYPO3 only writes log entries when a user accesses the system that uses a deprecated component.

The following two features are particularly useful to run before you execute a TYPO3 upgrade: “Check TCA Migrations” and “Scan Extension Files”. You can find both backend functions under Admin Tools ➜ Upgrade.

The first function identifies any third-party extensions that contain an outdated TCA configuration, which should be adapted. The second function scans installed extensions to check if they use deprecated or obsolete TYPO3 API calls. You find more information in the official TYPO3 documentation.

Now you know how the deprecation policy works and what you can and should do before updating one of your TYPO3 installations. Our backwards-compatibility promise covers the following technical items:

• Hooks and Signals (and Symfony Event Dispatchers since TYPO3 v10).
• CLI commands
• Backend routes
• PSR-15 middlewares

Configuration options are also covered unless a “silent upgrade” automatically migrates them. These options include configurations such as TYPO3_CONF_VARS, Form.yaml, RTE.yaml, and the site configuration, for example.

The Upgrade Wizard (“Admin Tools ➜ Upgrades ➜ Upgrade Wizard”) takes care of migration tasks, such as content updates and global configuration changes, if required.

At the same time, the deprecation policy explicitly excludes some items. This includes PHP classes for internal use only (marked with the annotation @internal) and dependencies on third-party Composer packages. We usually update these packages for every major TYPO3 release, and when we have to between releases. The deprecation policy does not cover the deprecations of backend components such as JavaScript code, CSS code, HTML code, and backend templates.

Imagine a situation when you deploy a bugfix version of TYPO3 (for example, an update from version 12.4.8 to 12.4.9) and the frontend of your website breaks due to TypoScript or Fluid changes. This scenario would be a nightmare for every TYPO3 integrator and administrator responsible for a website, no matter its size and complexity.

Don’t worry: your frontend is safe!
Bugfix releases of TYPO3 never break the frontend output. Existing TypoScript settings and the way Fluid templates are processed and rendered don’t change when you deploy a bugfix release.

In summary, I would like to give you some advice: Deploying a TYPO3 bugfix version should be straightforward, but before you execute an upgrade between two LTS-releases, enable deprecation logging and carefully review the log file. Also, check the necessary TCA migrations and use the Extension Scanner. Take action before the upgrade, as required. Executing the Upgrade Wizard is an essential and mandatory step in every TYPO3 upgrade process, particularly in LTS-to-LTS upgrades.

As an extension author, you should make sure that your publicly available extensions are always compatible with at least two major versions. Make sure to keep an eye on the changes introduced in sprint releases and thoroughly test your extension before an LTS-version is released.