--- title: "Apply Changelog entries to the docs" manual: "How to Document" version: "main" permalink: "https://docs.typo3.org/permalink/h2document:update-docs" source: "Maintainers/Changelog.rst" rendered: "2026-10-02T17:59:41+00:00" --- # Apply Changelog entries to the docs {#update-docs} Whenever a change to the TYPO3 Core potentially affects the users a changelog entry is created or edited, for example: The hook $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_userauth.php']['logoff_pre_processing'] is deprecated since TYPO3 12.3, use the event BeforeUserLogoutEvent instead. See Deprecation: #100307 - Various hooks related to authentication users. > [!NOTE] > **See also** > > See [What belongs in a version directive](https://docs.typo3.org/permalink/h2document:rest-versions-what-belongs-in-directive) > for what belongs in the directive body versus the regular text around it. 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. **Table of contents** - [Commit messages](https://docs.typo3.org/permalink/h2document:commit-messages) - [One pull request per issue](https://docs.typo3.org/permalink/h2document:one-pull-request-per-issue) - [Which TYPO3 versions were affected?](https://docs.typo3.org/permalink/h2document:which-typo3-versions-were-affected) - [Deprecations in the Changelog](https://docs.typo3.org/permalink/h2document:deprecations-in-the-changelog) - [Breaking changes in the Changelog](https://docs.typo3.org/permalink/h2document:breaking-changes-in-the-changelog) - [New features in the Changelog](https://docs.typo3.org/permalink/h2document:new-features-in-the-changelog) ## Commit messages {#howto-update-docs-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](https://docs.typo3.org/permalink/h2document:commit-messages) for the full picture), for example: **Example commit message** ```text [FEATURE] Add ApplicationContext to TypoScript data Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790 Releases: main Assisted-by: Claude Sonnet 5 Signed-off-by: Jane Doe ``` ## One pull request per issue {#howto-update-docs-one-pr-per-issue} Document each [Changelog-To-Doc issue](https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues) 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?](https://docs.typo3.org/permalink/h2document:changelog-affected-versions)), a self-contained pull request can be reverted cleanly, without pulling in unrelated documentation changes along with it. ## Which TYPO3 versions were affected? {#changelog-affected-versions} 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](https://docs.typo3.org/permalink/h2document:backport-changes) to use. The source of truth is the changelog entry's own path in [typo3/typo3](https://github.com/TYPO3/typo3), under `Documentation/Changelog//`. 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](https://review.typo3.org) (for example [https://review.typo3.org/c/Packages/TYPO3.CMS/+/85987](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 {#changelog-deprecations} All information about deprecations should be marked with the `.. deprecated::` directive and the version of deprecation. The hook $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_userauth.php']['logoff_pre_processing'] is deprecated since TYPO3 12.3, use the event BeforeUserLogoutEvent instead. See Deprecation: #100307 - Various hooks related to authentication users. ```rst .. deprecated:: 12.3 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. See `Deprecation: #100307 - Various hooks related to authentication users `_. ``` 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 {#changelog-breaking-changes} Ideally a breaking change was prepared by a [deprecation](https://docs.typo3.org/permalink/h2document:changelog-deprecations) 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. The widely used ->execute() method has been split into ->executeQuery() and ->executeStatement(). See Deprecation: #96972 - Deprecate QueryBuilder::execute(). ```rst .. versionchanged:: 12.0 The widely used :php:`->execute()` method has been split into :php:`->executeQuery()` and :php:`->executeStatement()`. See `Deprecation: #96972 - Deprecate QueryBuilder::execute() `_. ``` For emphasis you can also put the version changed directive into a warning or info box: > [!WARNING] > > > The widely used ->execute() method has been split into > ->executeQuery() and ->executeStatement(). > See Deprecation: #96972 - Deprecate QueryBuilder::execute(). ```rst .. warning:: .. versionchanged:: 12.0 The widely used :php:`->execute()` method has been split into :php:`->executeQuery()` and :php:`->executeStatement()`. See `Deprecation: #96972 - Deprecate QueryBuilder::execute() `_. ``` Using the correct directive will help us to track down and remove these hints in later versions. ## New features in the Changelog {#changelog-feature} 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: A PHP attribute \TYPO3\CMS\Core\Attribute\AsEventListener is available to autoconfigure a class as an event listener. See Feature: #101544 - Introduce PHP attribute to autoconfigure event listeners. 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.