[TASK] Update tags for all rst files for 8.0
[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 Different changelog types
31 =========================
32
33 A changelog handles one of these change types:
34
35 - Breaking change: A patch moved or removed a specific part of core functionality that may break extensions if they use this part. Removal of deprecated code or an interface change are good examples of this type.
36
37 - Deprecation: A patch deprecates a certain core functionality for a planned removal.
38
39 - Feature: A patch adds new functionality.
40
41 - Important: Any other important message.
42
43 Casual bug fixes do not need changelog files, but every change that may be of special interest for extension developers
44 or documentation writers should receive an entry. The changelog file must be provided as part of the patch that
45 introduces the change.
46
47
48 Location
49 ========
50
51 New changelog files should be added to the "master" directory. If a version is to be released, all files in this directory
52 will be moved to a directory that is named after the release number. This way it can be easily seen which change was
53 introduced in which released core version.
54
55
56 Filename convention
57 ===================
58
59 <type>-<forgeIssueNumber>-<UpperCamelCaseDescription>.rst
60
61
62 File content
63 ============
64
65 Like other documentation, changelog files are done in ReST, see `TYPO3 wiki ReST syntax`_ for more details.
66
67 - All types contain a "Description" section that should give a short summary on which core part was affected by the change.
68
69 - All types contain an "Impact" section that describes the possible impact of a change. An example is "Frontend output may change", "Configuration of xy is easier" or "Backend will throw a fatal error".
70
71 - Types "Deprecation" and "Breaking" contain an "Affected installations" section that describes when and if a TYPO3 instance 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".
72
73 - Types "Deprecation" and "Breaking" contain a "Migration" section to describe best practices on how to cope with a specific change.
74
75 .. _TYPO3 wiki ReST syntax: http://wiki.typo3.org/ReST_Syntax