Skip to content

Commit 528c056

Browse files
AlagtsAlagts
committed
[TASK] Add description why and when TYPO3 updates should be performed
Resolves: #451 Releases: main, 13, 12
1 parent 12a3f97 commit 528c056

File tree

2 files changed

+185
-0
lines changed

2 files changed

+185
-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: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
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 the TYPO3 core developers present you the best
18+
version of TYPO3 CMS currently available on the market. It has the newest security features and the
19+
most amount of useful features. That is why you should always want to have your
20+
TYPO3 instances on the newest version possible. Another advantage is that you get free security fixes.
21+
22+
In TYPO3 however, we follow a specific cycle which usually takes 1.5 years long. Every
23+
1 and a half year a new TYPO3 version occurs. You can follow the cycle `here <https://typo3.org/cms/roadmap>`__.
24+
25+
We explain the different parts in the `roadmap <https://typo3.org/cms/roadmap>`__ now.
26+
When you follow the roadmap you see dark red strokes. They represent the **sprint releases**.
27+
Sprint release is a version that starts for example with v13.0 and then the next sprint release follows with v13.1.
28+
After the last sprint release (v13.3) the **Long Term Support release (LTS release)** v13.4 follows.
29+
The aim of the sprint releases is to test the new code with the new features extensively, until the LTS-release is
30+
reached. Therefore, the reason for sprint releases is to make the new code with the new features as agile and stable
31+
as possible. The order is: sprint release (0), sprint release (1), sprint release (2), sprint release (3), LTS release (4).
32+
Sometimes more sprint releases are possible.
33+
34+
The green area represents the **regular maintenance** state. The orange area is the time where the focus lays on fixing
35+
bugs - so it is the **bug fixing phase**. The light orange area corresponds to the **extended support**. This means, when
36+
you want to get further bugfixes you have to book an
37+
`extended support <https://typo3.com/services/extended-support-elts>`__ which usually costs money.
38+
39+
In the following we look a bit deeper into the types of updates. Otherwise, when you feel safe with the concepts you
40+
can use the :ref:`Upgrade Guide <t3coreapi:upgrading>` as a general or later reference to perform updates.
41+
42+
.. _getting-started-major-minor-patchlevel-updates:
43+
44+
Major, minor and patch level updates
45+
====================================
46+
47+
In TYPO3 you can update your TYPO3 version. There exist three different types
48+
of updates:
49+
50+
#. Major updates: from for example 12.4.23 to 13.0.0
51+
#. Minor updates: from for example 13.0 to 13.1
52+
#. Patch and bugfix level updates (often security updates): from for example 13.4.0 to 13.4.1
53+
54+
55+
.. _getting-started-major-typo3-updates:
56+
57+
Major updates
58+
-------------
59+
60+
In major updates you will definitely have breaking changes and incompatible API
61+
changes.
62+
A breaking change can cause your system to break. You need to find a replacement
63+
for any usage that was removed or changed. For example in version 13.0 was a
64+
breaking change :ref:`Breaking: #101266 - Remove RequireJS <changelog:breaking-101266-1688654482>`.
65+
That means, whenever and wherever you used `requireJsModules` you have to find
66+
an replacement when you would like to have a working JavaScript functionality.
67+
All files that you included with `requireJsModules` will not be loaded anymore.
68+
When you update your TYPO3 version you should be aware of those changelog entries
69+
which you can find in the :doc:`Changelog reference <changelog:Changelog-13#changelog-v13>`.
70+
When dealing with a major version updates you usually have to use the backend module called **Upgrade wizard**. This
71+
module will take care of database table changes that came along with the new TYPO3 version.
72+
In TYPO3, we can separate a TYPO3 update into three stages: the :ref:`pre-upgrade stage <t3coreapi:preupgradetasks>`,
73+
:ref:`actual update <t3coreapi:upgradecore>` and the :ref:`post-upgrade stage <t3coreapi:postupgradetasks>`.
74+
75+
.. _getting-started-minor-typo3-updates:
76+
77+
Minor updates
78+
-------------
79+
80+
Minor changes - `11.*.2`: For example 11.5 has new functionalities compared to
81+
11.4. The version 11.5 is compatible with 11. So withing a version like major
82+
11 the steps do not lead to breaking changes. For example in version 13.3
83+
compared to version 13.2 a new
84+
:ref:`Feature: #101252 - Introduce ErrorHandler for 403 errors with redirect option <changelog:feature-101252-1715447531>`
85+
was introduced.
86+
When performing minor updates you often have to clear the cache, run the Upgrade wizard and to run a database compare.
87+
Usually minor and patch changes are also referred to as **non-breaking** changes.
88+
89+
.. _getting-started-patchlevel-typo3-updates:
90+
91+
Patchlevel updates
92+
------------------
93+
94+
Patchlevel changes - `11.5.*`: The version 11.5.2 indicates a backwards-compatible bugfix or patch release.
95+
It can be for example a security update. Clear the cache and check if website is working as expected. For further
96+
information we refer to the :ref:`Patch/Bugfix update guide<t3coreapi:minor>`.
97+
98+
.. _getting-started-extension-updates:
99+
100+
Extension updates
101+
=================
102+
103+
In a TYPO3 instance you have usually have third party extensions installed. When you update your TYPO3 version you
104+
have to update the third party extensions too. In the **TYPO3 Extension Repository (TER)** you can enter the name of
105+
that extension and get information about supported TYPO3 versions. You find the TER `here <https://extensions.typo3.org/>`__.
106+
You will recognize that some extension developers stopped developing their extension further. We recommend that you only
107+
use third party extensions that are still supported.
108+
109+
Useful commands to simplify the updates of extensions can be found in the :ref:`Upgrade extensions guide <t3coreapi:upgradingextensions>`.
110+
111+
.. _getting-started-cronjobs:
112+
113+
Cron jobs
114+
=========
115+
116+
You can use cron jobs to do tasks that occur repeated. The backend module called
117+
:ref:`TYPO3 Scheduler <typo3/cms-scheduler:start>` can be used to perform a cronjob that you defined previously.
118+
In your terminal you can type
119+
120+
121+
.. code-block:: shell
122+
:caption: Create or open the crontab
123+
124+
crontab -e
125+
126+
to create a new job on unix-like operating systems. In :ref:`Setting up the cron job <typo3/cms-scheduler:cron-job>` you can
127+
see how this works. Normally you have to define the time interval in which the job should be performed frequently. To
128+
test your pattern you can insert it `here <https://crontab.guru/>`__ and test if it performs like you expect. When you
129+
are not familiar with cron jobs we refer to https://en.wikipedia.org/wiki/Cron. With a cron job you can for example
130+
create a fal cleanup or a sys history cleanup.
131+
132+
133+
.. _getting-started-deprecations:
134+
135+
Deprecations
136+
============
137+
138+
In TYPO3, deprecations indicate that a specific functionality will be removed in the next TYPO3 version. For further
139+
information we refer to the :ref:`article about deprecation <t3coreapi:deprecation>`. For example the
140+
:ref:`deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax <changelog:deprecation-105171-1727785626>`- notice is
141+
a deprecation notice telling you that in TYPO3 v14 you can't use the TypoScript syntax :typoscript:`INCLUDE_TYPOSCRIPT`
142+
to include TypoScript files anymore.
143+
144+
.. _getting-started-little-helpers:
145+
146+
Little Helpers: Rector and Fractor
147+
==================================
148+
149+
In general you can use extensions like `rector <https://github.com/sabbelasichon/typo3-rector/blob/main/README.md>`__
150+
or `fractor <https://github.com/andreaswolf/fractor>`__ to find and replace deprecations. To reach this you have to
151+
fill out a configuration file (in rector file :file:`rector.php`, in fractor file :file:`fractor.php`) that defines
152+
the scope in which you want to perform deprecation replacements. For both extension is valid, only the rules that
153+
exist can find the respective deprecation. Here is an overview about the
154+
`existing rector rules <https://github.com/sabbelasichon/typo3-rector/blob/main/docs/all_rectors_overview.md>`__.
155+
When a rule is missing you can't find the deprecation. Check `here <https://getrector.com/find-rule>`__ if your desired
156+
rector rule exists already. When you feel able to create your own rector or fractor rule and want to publish it to the
157+
TYPO3 community, everyone using these tools would be happy to profit from your effort.
158+
159+
.. _getting-started-logfile-rotations:
160+
161+
Log file rotations
162+
==================
163+
164+
165+
.. _getting-started-sys-log:
166+
167+
Sys log
168+
=======
169+
170+
We have to take care of sys_log errors.
171+
172+
.. _getting-started-language-updates:
173+
174+
Language updates
175+
================
176+
177+
After a TYPO3 update you have to update your translations. We refer to the article
178+
:ref:`Update backend translations <t3coreapi:update_backend_translation>`. You have to update the language packs that
179+
you are using.

0 commit comments

Comments
 (0)