Skip to content

Commit cd4b62d

Browse files
github-actions[bot]Alagts
github-actions[bot]
and
Alagts
authored
[Backport 12.4] [TASK] Add description why and when TYPO3 updates should be performed (#634)
* [TASK] Add description why and when TYPO3 updates should be performed Resolves: #451 Releases: main, 13, 12 * Add requested changes to /Installation/Updates/Index.rst --------- Co-authored-by: Sandra Erbel <[email protected]> Co-authored-by: Sandra Erbel <[email protected]>
1 parent 52f753a commit cd4b62d

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎Documentation/Installation/Index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Installation
1616
Install
1717
DeployTYPO3
1818
ApplicationContext
19+
Updates/Index
1920

2021
.. card-grid::
2122
:columns: 1
@@ -35,6 +36,11 @@ Installation
3536
This is a step-by-step guide detailing how to install TYPO3 for local
3637
development using DDEV, Docker and Composer.
3738

39+
.. card:: :ref:`TYPO3 Updates <getting-started-typo3-updates>`
40+
41+
Here we explain the cycle of TYPO3 updates, and show you why and when
42+
a TYPO3 update is useful.
43+
3844
.. card:: :ref:`Deploying TYPO3 <DeployTYPO3>`
3945

4046
After you have installed TYPO3 locally, learn how to move your result

‎Documentation/Installation/Updates/Index.rst‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _getting-started-typo3-updates:
4+
5+
=================
6+
Maintaining TYPO3
7+
=================
8+
9+
.. contents::
10+
:caption: Content on this page
11+
12+
.. _when-and-why-updates:
13+
14+
When and why should we perform TYPO3 updates?
15+
=============================================
16+
17+
With the newest version of TYPO3 you receive free bugfixes and free security patches
18+
for at least three years from the time of the first LTS minor (for example v13.1) release.
19+
20+
In TYPO3 however, we follow a specific cycle which usually takes 1.5 years long. Every
21+
1 and a half year a new TYPO3 version occurs. You can follow the cycle `here <https://typo3.org/cms/roadmap>`__.
22+
23+
We explain the different parts in the `roadmap <https://typo3.org/cms/roadmap>`__ now.
24+
When you follow the roadmap you see dark red strokes. They represent the **sprint releases**.
25+
Sprint release is a version that starts for example with v13.0 and then the next sprint release follows with v13.1.
26+
After the last sprint release (v13.3) the **Long Term Support release (LTS release)** v13.4 follows.
27+
The aim of the sprint releases is to test the new code with the new features extensively, until the LTS-release is
28+
reached. Therefore, the reason for sprint releases is to make the new code with the new features as agile and stable
29+
as possible. The order is: sprint release (0), sprint release (1), sprint release (2), sprint release (3), LTS release (4).
30+
Sometimes more sprint releases are possible.
31+
32+
The green area represents the **regular maintenance** state. The orange area is the time where the focus lays on fixing
33+
bugs - so it is the **bug fixing phase**. The light orange area corresponds to the **extended support**. This means, when
34+
you want to get further bugfixes you have to book an
35+
`extended support <https://typo3.com/services/extended-support-elts>`__ which usually costs money.
36+
37+
Before we look a bit deeper into the :ref:`types of updates <getting-started-major-minor-patchlevel-updates>`
38+
we summaries how a TYPO3 user should act with respect to TYPO3 updates:
39+
40+
* When a new major LTS version is released, users **should** focus on updating to this version as soon as possible.
41+
* When a new minor version is released, users **must** update to the new minor version, since the previous minor version is **not** supported any more.
42+
* When a new patch level version is released, users should always update to the new version, because it contains important bugfixes and security fixes (if announced). Here you find the `security advisories <https://typo3.org/help/security-advisories>`__.
43+
44+
Additionally, users should take care of updated extensions on a regular schedule
45+
in order to use the most recent versions.
46+
47+
When you feel safe with the concepts of TYPO3 updates you can in general use
48+
this :ref:`Upgrade Guide <t3coreapi:upgrading>`.
49+
50+
Now we explain the types of updates.
51+
52+
.. _getting-started-major-minor-patchlevel-updates:
53+
54+
Major, minor and patch level updates
55+
====================================
56+
57+
In TYPO3 you can update your TYPO3 version. There exist three different types
58+
of updates:
59+
60+
#. Major updates: from for example 12.4.23 to 13.0.0
61+
#. Minor updates: from for example 13.0 to 13.1
62+
#. Patch and bugfix level updates (often security updates): from for example 13.4.0 to 13.4.1
63+
64+
65+
.. _getting-started-major-typo3-updates:
66+
67+
Major updates
68+
-------------
69+
70+
In major updates you will definitely have breaking changes and incompatible API
71+
changes.
72+
A breaking change can cause your system to break. You need to find a replacement
73+
for any usage that was removed or changed. For example in version 13.0 was a
74+
breaking change :ref:`Breaking: #101266 - Remove RequireJS <changelog:breaking-101266-1688654482>`.
75+
That means, whenever and wherever you used `requireJsModules` you have to find
76+
an replacement when you would like to have a working JavaScript functionality.
77+
All files that you included with `requireJsModules` will not be loaded anymore.
78+
When you update your TYPO3 version you should be aware of those changelog entries
79+
which you can find in the :doc:`Changelog reference <changelog:Changelog-13#changelog-v13>`.
80+
When dealing with a major version updates you usually have to use the backend module called **Upgrade wizard**. This
81+
module will take care of database table changes that came along with the new TYPO3 version.
82+
In TYPO3, we can separate a TYPO3 update into three stages: the :ref:`pre-upgrade stage <t3coreapi:preupgradetasks>`,
83+
:ref:`actual update <t3coreapi:upgradecore>` and the :ref:`post-upgrade stage <t3coreapi:postupgradetasks>`.
84+
85+
.. _getting-started-minor-typo3-updates:
86+
87+
Minor updates
88+
-------------
89+
90+
Minor changes - `11.*.2`: For example 11.5 has new functionalities compared to
91+
11.4. The version 11.5 is compatible with 11. So withing a version like major
92+
11 the steps do not lead to breaking changes. For example in version 13.3
93+
compared to version 13.2 a new
94+
:ref:`Feature: #101252 - Introduce ErrorHandler for 403 errors with redirect option <changelog:feature-101252-1715447531>`
95+
was introduced.
96+
When performing minor updates you often have to clear the cache, run the Upgrade wizard and to run a database compare.
97+
Usually minor and patch changes are also referred to as **non-breaking** changes.
98+
99+
.. _getting-started-patchlevel-typo3-updates:
100+
101+
Patchlevel updates
102+
------------------
103+
104+
Patchlevel changes - `11.5.*`: The version 11.5.2 indicates a backwards-compatible bugfix or patch release.
105+
It can be for example a security update. Clear the cache and check if website is working as expected. For further
106+
information we refer to the :ref:`Patch/Bugfix update guide<t3coreapi:minor>`.
107+
108+
.. _getting-started-extension-updates:
109+
110+
Extension updates
111+
=================
112+
113+
In a TYPO3 instance you have usually third party extensions installed. When you update your TYPO3 version you
114+
have to update the third party extensions too. In the **TYPO3 Extension Repository (TER)** you can enter the name of
115+
that extension and get information about supported TYPO3 versions. You find the TER `here <https://extensions.typo3.org/>`__.
116+
Some extension authors prefer to only publish their extensions on `packagist <https://packagist.org/packages/typo3/>`__.
117+
When the extension does not exist for the current TYPO3 version you can create an
118+
issue or search for an alternative extension offering the same functionality.
119+
For example the `gridelements extension<https://extensions.typo3.org/extension/gridelements>`__
120+
was replaced by the `container extension<https://extensions.typo3.org/extension/container>`__, both
121+
having equal functionalities.
122+
123+
Useful commands to simplify the updates of extensions can be found in the :ref:`Upgrade extensions guide <t3coreapi:upgradingextensions>`.
124+
125+
.. _getting-started-deprecations:
126+
127+
Deprecations
128+
============
129+
130+
In TYPO3, deprecations indicate that a specific functionality will be removed in the next TYPO3 version. For further
131+
information we refer to the :ref:`article about deprecation <t3coreapi:deprecation>`. For example the
132+
:ref:`deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax <changelog:deprecation-105171-1727785626>`- notice is
133+
a deprecation notice telling you that in TYPO3 v14 you can't use the TypoScript syntax :typoscript:`INCLUDE_TYPOSCRIPT`
134+
to include TypoScript files anymore.
135+
136+
.. _getting-started-little-helpers:
137+
138+
Little Helpers: Rector and Fractor
139+
==================================
140+
141+
In general you can use extensions like `rector <https://github.com/sabbelasichon/typo3-rector/blob/main/README.md>`__
142+
or `fractor <https://github.com/andreaswolf/fractor>`__ to find and replace deprecations. To reach this you have to
143+
fill out a configuration file (in rector file :file:`rector.php`, in fractor file :file:`fractor.php`) that defines
144+
the scope in which you want to perform deprecation replacements. For both extension is valid, only the rules that
145+
exist can find the respective deprecation. Here is an overview about the
146+
`existing rector rules <https://github.com/sabbelasichon/typo3-rector/blob/main/docs/all_rectors_overview.md>`__.
147+
When a rule is missing you can't find the deprecation. Check `here <https://getrector.com/find-rule>`__ if your desired
148+
rector rule exists already. If you feel able to create your own rector or fractor rule and want to share it with the TYPO3
149+
community, everyone using these tools would be happy to benefit from your efforts.
150+
151+
.. _getting-started-language-updates:
152+
153+
Language updates
154+
================
155+
156+
After a TYPO3 update you have to update your translations. We refer to the article
157+
:ref:`Update backend translations <t3coreapi:update_backend_translation>`. You have to update the language packs that
158+
you are using after each TYPO3 update.

0 commit comments

Comments
 (0)