Update documentation for new releases

Once a new TYPO3 release comes out, the main documentation (e.g. t3coreapi:start, t3tca:start etc.) must be updated.

Here, we describe some best practices for updating the official documentation for a new TYPO3 release. We stick to the core conventions as much as possible because that makes it easier for everyone to contribute to documentation and core.

How to handle deprecations and breaking changes

重要

We used to follow the conventions, that deprecated features were entirely removed from the documentation as soon as they are deprecated. This no longer applies: We recommend to add some information about the deprecation where this may be helpful.

This has the disadvantage that the documentation must be modified twice: once to point out the deprecation, and finally to remove it.

But, on the other hand, we have found that it is more user friendly to document the deprecation and the alternative to make migration easier. This mean, we do not (yet) remove the deprecated information entirely. This gives people more time to adjust to the changes. Also, deprecated features may still be used, but if the documentation were removed entirely, a search for documentation would direct everyone to a previous version where the feature is still documented without mentioning the deprecation.

See the next section for some examples.

How to add version hints

Example, how you can point out deprecations:

バージョン 10.2 で撤廃: The hook shown here is deprecated since TYPO3 10.2 - use a custom PSR-15 middleware instead.

New feature:

.. versionadded:: 10.2
   Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
   event dispatching system.

Changes:

.. versionchanged:: 2.3.1
   This feature was changed ...

Further information:

Issues

  • It is not necessary to create an issue for every change.

Commit messages

The commit message can point out the releases to which the change should apply (as in the core commits), e.g. Releases: master, 9.5, see Commit messages.

You can link to the issue for the changes in the team repository, for example:

Related: TYPO3-Documentation/T3DocTeam#121

Applying changes to several releases

Sometimes a necessary change applies to several major versions. Example: A change in the documentation is necessary in current master (10) and also in 9.5 branch.

If this is the case, it is recommended to:

  • apply the change to the lower version (9.5 in our example) first, and then create another PR for the higher version making necessary additional changes. This is the reverse order of what is being used in the core!
  • The person merging the commit should take care of merging into other branches as well (in case that is necessary). This is the same convention as in the core.
  • The changes can be bundled into one commit and the commit / PR can have a subject such as:
[TASK] Update with changes from 9.5.3

This makes it easier to find related changes and check for which version a branch was last updated.

How to mark what state a manual is in

In order to keep track of which changes have already been applied and give readers hints about how up to date a manual is, you can optionally add a "Status" to the start page (Documentation/Index.rst).

For example:

:Status:
   ok (Fully reviewed for TYPO3 9.5.9 on July 22, 2019)

If the manual has not been fully reviewed, but all changelogs up to 9.5.9 have been applied, you might use:

:Status:
   needs review (All changelogs <= TYPO3 9.5.9 have been applied)

See t3start:start.