77c6dba51755bea27ac11a9277adf556c1f64abc
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / Howto.rst
1
2 .. include:: ../Includes.txt
3
4 ===================
5 Documenting Changes
6 ===================
7
8 Motivation and goals
9 ====================
10
11 .. sidebar:: Forger
12
13    If you want to save yourself some time you can use the ReST-File-Generator at https://forger.typo3.org/utility/rst
14
15    Select the type of ReST snippet you want to create, enter your issue number and click the search button.
16
17 Spreading information about important core changes has been a problematic issue ever since. With the switch to the
18 new release cycle with version 7 of the TYPO3 CMS core this situation should be improved.
19
20 A dedicated changelog of important changes is established to inform users, developers and other core related
21 teams or projects:
22
23 - Overview for documentation team which changes trigger documentation changes.
24
25 - Overview for Release Managers and other "Spread the word" related works on important changes.
26
27 - Hints for extension developers, integrators and project developers whose own code areas may need adjustments on core updates.
28
29 - Standardized format for easy usage in scripts like a core migration or release notes system.
30
31 This structure replaces the old `NEWS.md` file.
32
33
34 Different changelog types
35 =========================
36
37 A changelog handles one of these change types:
38
39 - Breaking change: A patch moved or removed a specific part of core functionality that may break extensions if they use
40   this part. Removal of deprecated code or an interface change are good examples of this type.
41
42 - Deprecation: A patch deprecates a certain core functionality for a planned removal.
43
44 - Feature: A patch adds new functionality.
45
46 - Important: Any other important message.
47
48 Casual bug fixes do not need changelog files, but every change that may be of special interest for extension developers
49 or documentation writers should receive an entry. The changelog file must be provided as part of the patch that
50 introduces the change.
51
52
53 Location
54 ========
55
56 New changelog files should usually be added to the :file:`typo3/sysext/core/Documentation/Changelog/master` directory. If a
57 version is to be released, all files in this directory will be moved to a directory that is named after the release number.
58 This way it can be easily seen which change has been introduced in which released core version.
59
60 In rare cases, patches worth a changelog file need to be back ported to stable LTS and / or old stable LTS versions. Those
61 should be put into a different directory, depending on target LTS versions. We'll explain this by example:
62
63 Suppose core is currently developing v9, a first 9.0 has been released, so git core branch `master` will become 9.1.0 with
64 next sprint release.
65 Stable LTS version is currently 8.7.9, git core branch `TYPO3_8-7` will become 8.7.10 with next stable LTS patch level release.
66 Old stable LTS version is currently 7.6.23, git core branch `TYPO3_7-6` will become 7.6.24 with next old stable LTS
67 patch level release.
68
69 Example scenarios:
70
71 * **A feature patch is added to master:** Put the .rst file into the :file:`master/` directory. The core team will re-review
72   files in this directory shortly before 9.1.0 release and will move all files from :file:`master` into :file:`9.1` directory.
73
74 * **A patch with an important change in behavior is not only added to master, but also to 8.7:** Put the .rst file into the
75   :file:`8.7.x` directory in `master` branch. The back port to `TYPO3_8-7` branch includes the changelog file into
76   :file:`8.7.x` directory, too. Users upgrading to latest patch level release of 8.7 will then see the new file in
77   the :file:`8.7.x` directory.
78
79 * **A patch with an important change in behavior is not only added to master, but back ported to 8.7 and to 7.6:** Put the .rst
80   into :file:`8.7.x` directory, duplicate the file and also add it to :file:`7.6.x` directory in the `master` branch. The
81   back port to `TYPO3_8-7` branch adds these two files as well. The patch to `TYPO3_7-6` branch adds only the file in the
82   :file:`7.6.x` directory, not the file in :file:`8.7.x` directory.
83   Users upgrading to latest 7.6 patch level will then see the new file in :file:`7.6.x` directory, users upgrading to
84   latest 8.7 patch level will see the a new file in :file:`7.6.x` directory, and also in :file:`8.7.x` directory.
85
86 The main goal of this approach is to have a consistent state of changelog file across branches. Changelog files from
87 older releases are never deleted in younger branches. They are still rendered in the install tool
88 "View Upgrade Documentation" and are connected to the "Extension scanner". In our example above, master contains
89 all changelog files for v9, and v8 and v7 files, branch `TYPO3_8-7` contains all files for v8 and v7, and branch
90 `TYPO3_7-6` contains all v7 files.
91
92 Furthermore, documentation files from older releases should be identical in all branches. If a patch improves some
93 documentation file from a v7 directory, this change should be put into all branches: `master`, `TYPO3_8-7`
94 and `TYPO3_7-6` for consistency. The core team will check for differences of files between branches occasionally
95 and will align them in case they diverged.
96
97
98 Filename convention
99 ===================
100
101 <type>-<forgeIssueNumber>-<UpperCamelCaseDescription>.rst
102
103
104 File content
105 ============
106
107 Like other documentation, changelog files are done in ReST, see `TYPO3 wiki ReST syntax`_ for more details.
108
109 - All types contain a "Description" section that should give a short summary on which core part was affected by the change.
110
111 - All types contain an "Impact" section that describes the possible impact of a change. An example is "Frontend output
112   may change", "Configuration of xy is easier" or "Backend will throw a fatal error".
113
114 - Types "Deprecation" and "Breaking" contain an "Affected installations" section that describes when and if a TYPO3 instance
115   is affected by a change. Example: "Extension xy is in use" or "TypoScript functionality xy is used" or "System is based on PHP 5.3".
116
117 - Types "Deprecation" and "Breaking" contain a "Migration" section to describe best practices on how to cope with a specific change.
118
119 - All types contain a list of tags, see below.
120
121 .. _TYPO3 wiki ReST syntax: http://wiki.typo3.org/ReST_Syntax
122
123
124 Tagging
125 =======
126
127 To provide the possibility to filter ReST files by topics, it is mandatory to equip every RST file with at least two tags.
128 As a rule of thumb a file should have no more than five tags. Please limit yourself to the list provided below. If you
129 are in dearly need to introduce a new tag, you must also add it to the list (and explain it) in this file as a reference
130 for everyone.
131
132 The tag list should be located at the end of a ReST file prefixed with the index keyword,
133 example:: ``.. index:: Backend, JavaScript, NotScanned``.
134
135 List of all possible tags:
136
137 - TypoScript - Changes that imply or introduce alterations to some TypoScript settings or modify the behavior of TypoScript
138   itself. Frontend TypoScript only.
139
140 - TSConfig - Changes or modifications on the PageTS or UserTS or the behavior of this field.
141
142 - TCA - Every change related to TCA.
143
144 - FlexForm - Changes affecting FlexForm functionality.
145
146 - LocalConfiguration - Changes that affect the LocalConfiguration.php or the subordinated AdditionalConfiguration.php
147
148 - Fluid - Changes that alter behavior of Fluid like introducing new tags or modifying already established ones.
149
150 - FAL - Changes to File Abstraction Layer.
151
152 - Database - Changes that modify behavior of the database abstraction or introduces or removes new fields.
153
154 - JavaScript - Modifying or introducing JavaScript.
155
156 - PHP-API - Implementations of mandatory changes of the PHP-API.
157
158 - Frontend - Changes that will affect the behavior or rendering of the TYPO3 Frontend.
159
160 - Backend - Changes that will affect the behavior or rendering of the TYPO3 Backend.
161
162 - CLI - Changes affecting CLI functionality.
163
164 - RTE - Changes to RTE functionality.
165
166 - ext:xyz - Changes on extension xyz. Please refer to this tag only when changing system extensions.
167
168 Furthermore, exactly one of the following tags *must* be added for all "Deprecation" and "Breaking" ReST files since core v9 and above:
169
170 - NotScanned - If this ReST file is not covered by the extension scanner at all.
171
172 - PartiallyScanned - If some parts of the deprecated / removed functionality can be found by the extension scanner.
173
174 - FullyScanned - If usages of all deprecated / removed functionality this ReST file is about can be found by the
175   extension scanner. This tag is used by the extension scanner to mark a ReST file as "You are not affected by this in your codebase"
176   if it does not find a match in extensions.