Apply Changelog entries to the docs 

Triage new issues 

A new issue in Changelog-To-Doc only has a version label, such as 15.0 or 14.3.x. Triage decides whether the change needs documentation and where. Each issue ends in one of three ways:

• No docs needed: label No docs needed, comment why, and close the issue.
• Needs documenting: label the manual and the type of change, and comment which pages need to change and how. The issue stays open.
• Already documented: comment where, and close the issue without the label No docs needed.

Commit messages 

All changes that are related to such an issue should contain a reference in their commit message to the issue (see commit message conventions for the full picture), for example:

[FEATURE] Add ApplicationContext to TypoScript data

Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
Releases: main
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Jane Doe

One pull request per issue 

Document each Changelog-To-Doc issue in its own pull request, with a title matching the issue's own title. Do not bundle documentation for several issues into a single pull request, even if they touch the same page.

This also makes reverts easier: if a feature gets reverted before release (see Which TYPO3 versions were affected?), a self-contained pull request can be reverted cleanly, without pulling in unrelated documentation changes along with it.

Which TYPO3 versions were affected? 

Before writing the documentation, find out which TYPO3 version(s) the change actually shipped in - this decides which docs branch(es) to work on and which Releases: trailer and backport labels to use.

The source of truth is the changelog entry's own path in typo3/typo3, under Documentation/Changelog/<version>/. That version is the earliest one the change shipped in - it then also applies to every later release, forward from that point on. For example:

• 14.3.x/Important-110591-CustomColumnsInTheWorkspacesModule.rst was introduced after the initial 14.3 LTS release, so it first appears in a later 14.3 patch release (14.3.22) and is also part of 15.0.
• 14.2/Feature-108975-AddConfigurationProviderForExtbaseClassConfiguration.rst was part of 14.2.0, and therefore also of 14.3.0 and 15.0.
• 13.3/Feature-104878-IntroduceDashboardWidgetForPagesWithLatestChanges.rst was part of 13.3.0, 13.4.0, and every 14.x and 15.x release since.

The version label(s) already on the Changelog-To-Doc issue itself (for example 14.2) are a convenient shortcut - the issue is automatically labeled from that same path - but not the source of truth themselves.

Do not rely only on the Releases: trailer of the Core commit the issue links to. While a change is being developed, the version it targets is often simply main - a dedicated branch for that version does not exist yet. The trailer, written at commit time, reflects that and may only say main, even though main later becomes that specific version, and further versions branch off from that same point afterwards.

If you are documenting a feature that has not shipped yet - for example a feature planned for 15.0 before 15.0's first release - use that future version anyway, as decided on the roadmap. Documentation should be ready by the time a release ships, not written only afterwards.

If such a feature is reverted before release, the changelog file gets deleted and a new Changelog-To-Doc issue is opened for the revert - use that to roll back the corresponding documentation change.

You can also follow the issue's link to the change in Gerrit (for example https://review.typo3.org/c/Packages/TYPO3.CMS/+/85987), open the ⋮ menu in the upper right corner and select Included In - it lists every version the change was ever included in.

Deprecations in the Changelog 

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

..  deprecated:: 12.3
    :changelog: deprecation-100307-1679924603

    The hook :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_userauth.php']['logoff_pre_processing']`
    is deprecated since TYPO3 12.3, use the event
    :php-short:`\TYPO3\CMS\Core\Authentication\Event\BeforeUserLogoutEvent` instead.

In the ideal workflow a deprecation option will be removed with a breaking change in the next major version. We can then 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 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.

..  versionchanged:: 12.0
    :changelog: deprecation-96972

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

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

..  warning::
    ..  versionchanged:: 12.0
        :changelog: deprecation-96972

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

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 available in all supported TYPO3 versions, it can be helpful to mark it with the .. versionadded:: directive:

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.