[TASK] Changelog docs: Update Howto.rst 39/55139/3
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:16 +0000 (18:38 +0100)
Add more .rst file location information to the Changelog
"Documenting Changes" Howto.rst.
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/55139
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.rst
typo3/sysext/core/Documentation/Changelog/8.7.x/Index.rst [new file with mode: 0644]
typo3/sysext/core/Documentation/Changelog/Howto.rst

index 1c684be..94a7ec3 100644 (file)
@@ -11,6 +11,7 @@ Every change to the TYPO3 Core which might affect your site is documented here.
 .. toctree::
    :titlesonly:
 
+   Changelog/8.7.x/Index
    Changelog/8.7/Index
    Changelog/8.6/Index
    Changelog/8.5/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
+
+
+Features
+^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
+
+   Feature-*
+
+Important
+^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
+
+   Important-*
index 0e2ce2b..77c6dba 100644 (file)
@@ -1,3 +1,6 @@
+
+.. include:: ../Includes.txt
+
 ===================
 Documenting Changes
 ===================
@@ -50,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