From 67100c9e1cf7491261a35cffc19cb9f7a6ed900c Mon Sep 17 00:00:00 2001 From: Christian Kuhn <lolli@schwarzbu.ch> Date: Sun, 17 Dec 2017 17:23:47 +0100 Subject: [PATCH] [TASK] Changelog docs: Update Howto.rst Align Howto.rst with version from master. Change-Id: Ie68e5eb59f080537050717106bf549dc6d4a0ef3 Resolves: #83371 Releases: master, 8.7, 7.6 Reviewed-on: https://review.typo3.org/55141 Tested-by: TYPO3com <no-reply@typo3.com> Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch> Tested-by: Christian Kuhn <lolli@schwarzbu.ch> --- .../core/Documentation/Changelog/Howto.rst | 110 +++++++++++++++++- 1 file changed, 104 insertions(+), 6 deletions(-) diff --git a/typo3/sysext/core/Documentation/Changelog/Howto.rst b/typo3/sysext/core/Documentation/Changelog/Howto.rst index c39b47dd85af..77c6dba51755 100644 --- a/typo3/sysext/core/Documentation/Changelog/Howto.rst +++ b/typo3/sysext/core/Documentation/Changelog/Howto.rst @@ -30,12 +30,14 @@ teams or projects: This structure replaces the old `NEWS.md` file. + Different changelog types ========================= A changelog handles one of these change types: -- 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. +- 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. - Deprecation: A patch deprecates a certain core functionality for a planned removal. @@ -51,9 +53,46 @@ introduces the change. Location ======== -New changelog files should be added to the "master" directory. If a version is to be released, all files in this directory -will be moved to a directory that is named after the release number. This way it can be easily seen which change was -introduced in which released core version. +New changelog files should usually be added to the :file:`typo3/sysext/core/Documentation/Changelog/master` directory. If a +version is to be released, all files in this directory will be moved to a directory that is named after the release number. +This way it can be easily seen which change has been introduced in which released core version. + +In rare cases, patches worth a changelog file need to be back ported to stable LTS and / or old stable LTS versions. Those +should be put into a different directory, depending on target LTS versions. We'll explain this by example: + +Suppose core is currently developing v9, a first 9.0 has been released, so git core branch `master` will become 9.1.0 with +next sprint release. +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. +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 +patch level release. + +Example scenarios: + +* **A feature patch is added to master:** Put the .rst file into the :file:`master/` directory. The core team will re-review + files in this directory shortly before 9.1.0 release and will move all files from :file:`master` into :file:`9.1` directory. + +* **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 + :file:`8.7.x` directory in `master` branch. The back port to `TYPO3_8-7` branch includes the changelog file into + :file:`8.7.x` directory, too. Users upgrading to latest patch level release of 8.7 will then see the new file in + the :file:`8.7.x` directory. + +* **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 + into :file:`8.7.x` directory, duplicate the file and also add it to :file:`7.6.x` directory in the `master` branch. The + 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 + :file:`7.6.x` directory, not the file in :file:`8.7.x` directory. + Users upgrading to latest 7.6 patch level will then see the new file in :file:`7.6.x` directory, users upgrading to + 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. + +The main goal of this approach is to have a consistent state of changelog file across branches. Changelog files from +older releases are never deleted in younger branches. They are still rendered in the install tool +"View Upgrade Documentation" and are connected to the "Extension scanner". In our example above, master contains +all changelog files for v9, and v8 and v7 files, branch `TYPO3_8-7` contains all files for v8 and v7, and branch +`TYPO3_7-6` contains all v7 files. + +Furthermore, documentation files from older releases should be identical in all branches. If a patch improves some +documentation file from a v7 directory, this change should be put into all branches: `master`, `TYPO3_8-7` +and `TYPO3_7-6` for consistency. The core team will check for differences of files between branches occasionally +and will align them in case they diverged. Filename convention @@ -69,10 +108,69 @@ Like other documentation, changelog files are done in ReST, see `TYPO3 wiki ReST - All types contain a "Description" section that should give a short summary on which core part was affected by the change. -- 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". +- 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". -- 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". +- 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". - Types "Deprecation" and "Breaking" contain a "Migration" section to describe best practices on how to cope with a specific change. +- All types contain a list of tags, see below. + .. _TYPO3 wiki ReST syntax: http://wiki.typo3.org/ReST_Syntax + + +Tagging +======= + +To provide the possibility to filter ReST files by topics, it is mandatory to equip every RST file with at least two tags. +As a rule of thumb a file should have no more than five tags. Please limit yourself to the list provided below. If you +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 +for everyone. + +The tag list should be located at the end of a ReST file prefixed with the index keyword, +example:: ``.. index:: Backend, JavaScript, NotScanned``. + +List of all possible tags: + +- TypoScript - Changes that imply or introduce alterations to some TypoScript settings or modify the behavior of TypoScript + itself. Frontend TypoScript only. + +- TSConfig - Changes or modifications on the PageTS or UserTS or the behavior of this field. + +- TCA - Every change related to TCA. + +- FlexForm - Changes affecting FlexForm functionality. + +- LocalConfiguration - Changes that affect the LocalConfiguration.php or the subordinated AdditionalConfiguration.php + +- Fluid - Changes that alter behavior of Fluid like introducing new tags or modifying already established ones. + +- FAL - Changes to File Abstraction Layer. + +- Database - Changes that modify behavior of the database abstraction or introduces or removes new fields. + +- JavaScript - Modifying or introducing JavaScript. + +- PHP-API - Implementations of mandatory changes of the PHP-API. + +- Frontend - Changes that will affect the behavior or rendering of the TYPO3 Frontend. + +- Backend - Changes that will affect the behavior or rendering of the TYPO3 Backend. + +- CLI - Changes affecting CLI functionality. + +- RTE - Changes to RTE functionality. + +- ext:xyz - Changes on extension xyz. Please refer to this tag only when changing system extensions. + +Furthermore, exactly one of the following tags *must* be added for all "Deprecation" and "Breaking" ReST files since core v9 and above: + +- NotScanned - If this ReST file is not covered by the extension scanner at all. + +- PartiallyScanned - If some parts of the deprecated / removed functionality can be found by the extension scanner. + +- FullyScanned - If usages of all deprecated / removed functionality this ReST file is about can be found by the + 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" + if it does not find a match in extensions. -- GitLab