Commit 94058cd1 authored by Christian Kuhn's avatar Christian Kuhn
Browse files

[TASK] Changelog docs: Update Howto.rst

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: default avatarTYPO3com <no-reply@typo3.com>
Reviewed-by: Christian Kuhn's avatarChristian Kuhn <lolli@schwarzbu.ch>
Tested-by: Christian Kuhn's avatarChristian Kuhn <lolli@schwarzbu.ch>
parent e710b540
......@@ -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
......
.. 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-*
.. 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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment