[TASK] Changelog docs: Update Howto.rst 40/55140/4
authorChristian Kuhn <lolli@schwarzbu.ch>
Sun, 17 Dec 2017 16:23:47 +0000 (17:23 +0100)
committerChristian Kuhn <lolli@schwarzbu.ch>
Sun, 17 Dec 2017 17:38:41 +0000 (18:38 +0100)
Align Howto.rst with version from master.
Also add missing Index.rst entries for 8.7.x/ files.

Change-Id: Ie68e5eb59f080537050717106bf549dc6d4a0ef3
Resolves: #83371
Releases: master, 8.7, 7.6
Reviewed-on: https://review.typo3.org/55140
Tested-by: TYPO3com <no-reply@typo3.com>
Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: Christian Kuhn <lolli@schwarzbu.ch>
typo3/sysext/core/Documentation/Changelog/8.7.x/Index.rst [new file with mode: 0644]

index 1c684be..94a7ec3 100644 (file)
@@ -11,6 +11,7 @@ Every change to the TYPO3 Core which might affect your site is documented here.
 .. toctree::
+   Changelog/8.7.x/Index
diff --git a/typo3/sysext/core/Documentation/Changelog/8.7.x/Index.rst b/typo3/sysext/core/Documentation/Changelog/8.7.x/Index.rst
new file mode 100644 (file)
index 0000000..b186637
--- /dev/null
@@ -0,0 +1,34 @@
+.. include:: ../../Includes.txt
+8.7.x Changes
+Changes after 8.7.0 LTS release.
+**Table of contents**
+.. contents::
+   :local:
+   :depth: 1
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
+   Feature-*
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
+   Important-*
index 17e675c..77c6dba 100644 (file)
@@ -1,3 +1,6 @@
+.. include:: ../Includes.txt
 Documenting Changes
@@ -50,9 +53,46 @@ introduces the change.
-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
@@ -90,7 +130,7 @@ are in dearly need to introduce a new tag, you must also add it to the list (and
 for everyone.
 The tag list should be located at the end of a ReST file prefixed with the index keyword,
-example:: ``.. index:: Backend, JavaScript``.
+example:: ``.. index:: Backend, JavaScript, NotScanned``.
 List of all possible tags:
@@ -124,3 +164,13 @@ List of all possible tags:
 - 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.