Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

Apply changelog entries to the docs¶

Whenever a change to the TYPO3 Core potentially affects the users a changelog entry is created or edited, for example:

Deprecated since version 12.3

The hook shown here is deprecated since TYPO3 12.3, use the event XYZ instead.

Each Core change affecting the changelog automatically creates an Issue in the repository Changelog-To-Doc <https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues>. New issues here should be treated with priority.

Commit messages¶

All changes that are related to such an issue should contain a reference in their commit message to the issue, for example

Example commit message

[FEATURE] Add ApplicationContext to TypoScript data

Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
Releases: main

Deprecations in the changelog¶

All information about deprecations should be marked with the .. deprecated:: directive and the version of deprecation.

Deprecated since version 12.3

The hook shown here is deprecated since TYPO3 12.3, use the event XYZ instead.

..  deprecated:: 12.3
    The hook shown here is deprecated since TYPO3 12.3, use the event XYZ
    instead.

In the ideal workflow a deprecation option will be removed with a breaking change in the next major version. We can then just remove the deprecated section.

Using the correct directive will help the documentation team to find and remove deprecation hints in later versions.

Breaking changes in the changelog¶

Ideally a breaking change was prepared by a deprecation in the previous version. In this case we can just remove the deprecated section.

When important concepts changed that might confuse the users we sometimes leave a .. versionchanged:: directive to inform users where to head now.

Changed in version 11.5

The widely used ->execute() method has been split into: php:->executeQuery() and ->executeStatement(). Read more.

..  versionchanged:: 11.5
    The widely used :php:`->execute()` method has been split into:
    php:`->executeQuery()`  and :php:`->executeStatement()`. Read more.

For emphasis you can also put the version changed directive into a warning or info box:

Warning

Changed in version 11.5

The widely used ->execute() method has been split into: php:->executeQuery() and ->executeStatement(). Read more.

..  warning::
    ..  versionchanged:: 11.5
        The widely used :php:`->execute()` method has been split into:
        php:`->executeQuery()`  and :php:`->executeStatement()`. Read more.

Using the correct directive will help us to track down and remove these hints in later versions.

New features in the changelog¶

When adding a new feature to the docs that is not yet availible in all supported TYPO3 versions, it can be helpful to mark it with the .. versionadded:: directive:

New in version 13.0

A PHP attribute \TYPO3\CMS\Core\Attribute\AsEventListener is available to autoconfigure a class as an event listener...

This directive not only highlights new features but also assists users who are reading the manual in a version that does not align with their installation, ensuring clarity in cases where feature compatibility may differ.

The documentation team removes these directives when the feature is present in all supported TYPO3 versions.