[!!!][TASK] Migrate pages_language_overlay into pages
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / Howto.rst
1 ===================
2 Documenting Changes
3 ===================
4
5 Motivation and goals
6 ====================
7
8 .. sidebar:: Forger
9
10    If you want to save yourself some time you can use the ReST-File-Generator at https://forger.typo3.org/utility/rst
11
12    Select the type of ReST snippet you want to create, enter your issue number and click the search button.
13
14 Spreading information about important core changes has been a problematic issue ever since. With the switch to the
15 new release cycle with version 7 of the TYPO3 CMS core this situation should be improved.
16
17 A dedicated changelog of important changes is established to inform users, developers and other core related
18 teams or projects:
19
20 - Overview for documentation team which changes trigger documentation changes.
21
22 - Overview for Release Managers and other "Spread the word" related works on important changes.
23
24 - Hints for extension developers, integrators and project developers whose own code areas may need adjustments on core updates.
25
26 - Standardized format for easy usage in scripts like a core migration or release notes system.
27
28 This structure replaces the old `NEWS.md` file.
29
30
31 Different changelog types
32 =========================
33
34 A changelog handles one of these change types:
35
36 - Breaking change: A patch moved or removed a specific part of core functionality that may break extensions if they use
37   this part. Removal of deprecated code or an interface change are good examples of this type.
38
39 - Deprecation: A patch deprecates a certain core functionality for a planned removal.
40
41 - Feature: A patch adds new functionality.
42
43 - Important: Any other important message.
44
45 Casual bug fixes do not need changelog files, but every change that may be of special interest for extension developers
46 or documentation writers should receive an entry. The changelog file must be provided as part of the patch that
47 introduces the change.
48
49
50 Location
51 ========
52
53 New changelog files should be added to the "master" directory. If a version is to be released, all files in this directory
54 will be moved to a directory that is named after the release number. This way it can be easily seen which change was
55 introduced in which released core version.
56
57
58 Filename convention
59 ===================
60
61 <type>-<forgeIssueNumber>-<UpperCamelCaseDescription>.rst
62
63
64 File content
65 ============
66
67 Like other documentation, changelog files are done in ReST, see `TYPO3 wiki ReST syntax`_ for more details.
68
69 - All types contain a "Description" section that should give a short summary on which core part was affected by the change.
70
71 - All types contain an "Impact" section that describes the possible impact of a change. An example is "Frontend output
72   may change", "Configuration of xy is easier" or "Backend will throw a fatal error".
73
74 - Types "Deprecation" and "Breaking" contain an "Affected installations" section that describes when and if a TYPO3 instance
75   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".
76
77 - Types "Deprecation" and "Breaking" contain a "Migration" section to describe best practices on how to cope with a specific change.
78
79 - All types contain a list of tags, see below.
80
81 .. _TYPO3 wiki ReST syntax: http://wiki.typo3.org/ReST_Syntax
82
83
84 Tagging
85 =======
86
87 To provide the possibility to filter ReST files by topics, it is mandatory to equip every RST file with at least two tags.
88 As a rule of thumb a file should have no more than five tags. Please limit yourself to the list provided below. If you
89 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
90 for everyone.
91
92 The tag list should be located at the end of a ReST file prefixed with the index keyword,
93 example:: ``.. index:: Backend, JavaScript, NotScanned``.
94
95 List of all possible tags:
96
97 - TypoScript - Changes that imply or introduce alterations to some TypoScript settings or modify the behavior of TypoScript
98   itself. Frontend TypoScript only.
99
100 - TSConfig - Changes or modifications on the PageTS or UserTS or the behavior of this field.
101
102 - TCA - Every change related to TCA.
103
104 - FlexForm - Changes affecting FlexForm functionality.
105
106 - LocalConfiguration - Changes that affect the LocalConfiguration.php or the subordinated AdditionalConfiguration.php
107
108 - Fluid - Changes that alter behavior of Fluid like introducing new tags or modifying already established ones.
109
110 - FAL - Changes to File Abstraction Layer.
111
112 - Database - Changes that modify behavior of the database abstraction or introduces or removes new fields.
113
114 - JavaScript - Modifying or introducing JavaScript.
115
116 - PHP-API - Implementations of mandatory changes of the PHP-API.
117
118 - Frontend - Changes that will affect the behavior or rendering of the TYPO3 Frontend.
119
120 - Backend - Changes that will affect the behavior or rendering of the TYPO3 Backend.
121
122 - CLI - Changes affecting CLI functionality.
123
124 - RTE - Changes to RTE functionality.
125
126 - ext:xyz - Changes on extension xyz. Please refer to this tag only when changing system extensions.
127
128 Furthermore, exactly one of the following tags *must* be added for all "Deprecation" and "Breaking" ReST files since core v9 and above:
129
130 - NotScanned - If this ReST file is not covered by the extension scanner at all.
131
132 - PartiallyScanned - If some parts of the deprecated / removed functionality can be found by the extension scanner.
133
134 - FullyScanned - If usages of all deprecated / removed functionality this ReST file is about can be found by the
135   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"
136   if it does not find a match in extensions.