From 5a2584852c15ce3556b1003eee001d9e1beb1a01 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 17 Sep 2026 13:01:46 +0200 Subject: [PATCH 1/3] [FEATURE] Document the :changelog: option of the version directives The three version directives now take a :changelog: option that renders the link to the changelog entry in the version badge and resolves it through the changelog inventory. Until now the reference page showed only the hand-written permalink in the directive body, which is what the option replaces: it carries the same link text, taken from the entry's own title, and an entry that does not exist produces a build warning and the unresolved-reference marker rather than a link that leads nowhere. The section documents the three value forms (Core entry id, another manual's shortcode plus anchor, the local "#anchor") and the embedded "text " form for the case where the resolved title does not describe the change. The examples stay code-block only, no live directive: the option is in render-guides main but not in 0.41.0, which is what renders docs.typo3.org today. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_01NxSeVq1hDnGBCqKLGcjQ6m Agent-Host: 32116e Signed-off-by: Sebastian Mendel --- .../ReStructuredText/Content/Versions.rst | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Content/Versions.rst b/Documentation/Reference/ReStructuredText/Content/Versions.rst index 6e2450db..56935c9a 100644 --- a/Documentation/Reference/ReStructuredText/Content/Versions.rst +++ b/Documentation/Reference/ReStructuredText/Content/Versions.rst @@ -123,3 +123,59 @@ Find a changelog entry's permalink from its own `.. _--:` anchor, for example in the "Added files" section of the corresponding `Changelog-To-Doc `__ issue. + +.. _rest-versions-changelog-option: + +Linking the changelog entry with :rst:`:changelog:` +================================================== + +The examples above write the changelog permalink by hand into the +directive body. The three directives also accept a :rst:`:changelog:` +option, which renders the link in the version badge itself and resolves +the entry through the changelog inventory: + +.. code-block:: rst + + .. versionchanged:: 14.0 + :changelog: feature-107628-1729026000 + + Most modules have been moved from :guilabel:`System` to + :guilabel:`Administration`. + +The link text is the title of the entry the option resolves to, so it +reads the same as a hand-written permalink does today, without having to +copy the title and the URL. An entry that does not exist produces a build +warning and the unresolved-reference marker instead of a link that leads +nowhere, which a hand-written permalink cannot do. + +The option takes three forms: + +.. code-block:: rst + + .. TYPO3 Core: the changelog entry identifier on its own + .. versionchanged:: 14.0 + :changelog: feature-107628-1729026000 + + .. Another manual: its interlink shortcode, then the entry anchor + .. versionchanged:: 2.0 + :changelog: acme/acme-blog:changes-2-0-0 + + .. This manual's own changelog: the short "#anchor" form + .. versionchanged:: 2.1 + :changelog: #changes-2-1-0 + +Where the resolved title does not describe the change -- an extension +whose whole changelog page carries a single label, for instance -- give +the text explicitly, in the same embedded form every other reference +uses: + +.. code-block:: rst + + .. versionchanged:: 2.0 + :changelog: Renaming the teaser field + + The teaser field was renamed; see the changelog entry for the + migration. + +The entry itself is always a single token; only a text you supply may +contain spaces. From 2c0351706b2e4249ca21be9865470c35e83c77b6 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 17 Sep 2026 13:38:30 +0200 Subject: [PATCH 2/3] [TASK] Fix the house style of the :changelog: section Three things from a re-read against the repo's own conventions: The heading underline was one character short of the title, which docutils would object to even though the render did not. The section used " -- " as a dash where the file, and the manual around it, use " - " (84 occurrences against 8). "The option takes three forms" read as if the embedded "text " form were a fourth. The three are ways to address the entry; the embedded form wraps any of them. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_01NxSeVq1hDnGBCqKLGcjQ6m Agent-Host: 32116e Signed-off-by: Sebastian Mendel --- .../Reference/ReStructuredText/Content/Versions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Content/Versions.rst b/Documentation/Reference/ReStructuredText/Content/Versions.rst index 56935c9a..9b3d549b 100644 --- a/Documentation/Reference/ReStructuredText/Content/Versions.rst +++ b/Documentation/Reference/ReStructuredText/Content/Versions.rst @@ -127,7 +127,7 @@ issue. .. _rest-versions-changelog-option: Linking the changelog entry with :rst:`:changelog:` -================================================== +=================================================== The examples above write the changelog permalink by hand into the directive body. The three directives also accept a :rst:`:changelog:` @@ -148,7 +148,7 @@ copy the title and the URL. An entry that does not exist produces a build warning and the unresolved-reference marker instead of a link that leads nowhere, which a hand-written permalink cannot do. -The option takes three forms: +The entry can be addressed in three ways: .. code-block:: rst @@ -164,8 +164,8 @@ The option takes three forms: .. versionchanged:: 2.1 :changelog: #changes-2-1-0 -Where the resolved title does not describe the change -- an extension -whose whole changelog page carries a single label, for instance -- give +Where the resolved title does not describe the change - an extension +whose whole changelog page carries a single label, for instance - give the text explicitly, in the same embedded form every other reference uses: From 5f5f9e9aa389616a2d5100bfe3362ad1bd7cf516 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 27 Sep 2026 00:35:53 +0200 Subject: [PATCH 3/3] [TASK] Show the rendered :changelog: option and keep to Core entries The section now shows a live versionchanged directive under the code example. The renderer supports the option since render-guides 0.42.0, so the page shows the resolved link in the version badge. The section now covers only entries of the TYPO3 Core changelog. The interlink form, the local "#anchor" form and the embedded "text " form are edge cases, so the section does not describe them. The headline uses inline code instead of the :rst: role, because a role in a headline renders incorrectly. Assisted-by: Claude Opus 5.5 Agent-Session: https://claude.ai/code/session_01Q23BuF75uotqYJZhYxgbn9 Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel --- .../ReStructuredText/Content/Versions.rst | 57 ++++++------------- 1 file changed, 16 insertions(+), 41 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Content/Versions.rst b/Documentation/Reference/ReStructuredText/Content/Versions.rst index 9b3d549b..104f82b7 100644 --- a/Documentation/Reference/ReStructuredText/Content/Versions.rst +++ b/Documentation/Reference/ReStructuredText/Content/Versions.rst @@ -126,56 +126,31 @@ issue. .. _rest-versions-changelog-option: -Linking the changelog entry with :rst:`:changelog:` -=================================================== +Linking the changelog entry with `:changelog:` +============================================== -The examples above write the changelog permalink by hand into the -directive body. The three directives also accept a :rst:`:changelog:` -option, which renders the link in the version badge itself and resolves -the entry through the changelog inventory: +The examples above write the permalink of the changelog entry by hand into +the directive body. The three version directives also accept the +:rst:`:changelog:` option. Use this option to link an entry of the TYPO3 +Core changelog. The value is the identifier of the entry, in the form +`--`: .. code-block:: rst .. versionchanged:: 14.0 :changelog: feature-107628-1729026000 - Most modules have been moved from :guilabel:`System` to + Most modules moved from :guilabel:`System` to :guilabel:`Administration`. -The link text is the title of the entry the option resolves to, so it -reads the same as a hand-written permalink does today, without having to -copy the title and the URL. An entry that does not exist produces a build -warning and the unresolved-reference marker instead of a link that leads -nowhere, which a hand-written permalink cannot do. +.. versionchanged:: 14.0 + :changelog: feature-107628-1729026000 -The entry can be addressed in three ways: + Most modules moved from :guilabel:`System` to + :guilabel:`Administration`. -.. code-block:: rst - - .. TYPO3 Core: the changelog entry identifier on its own - .. versionchanged:: 14.0 - :changelog: feature-107628-1729026000 - - .. Another manual: its interlink shortcode, then the entry anchor - .. versionchanged:: 2.0 - :changelog: acme/acme-blog:changes-2-0-0 - - .. This manual's own changelog: the short "#anchor" form - .. versionchanged:: 2.1 - :changelog: #changes-2-1-0 - -Where the resolved title does not describe the change - an extension -whose whole changelog page carries a single label, for instance - give -the text explicitly, in the same embedded form every other reference -uses: - -.. code-block:: rst - - .. versionchanged:: 2.0 - :changelog: Renaming the teaser field - - The teaser field was renamed; see the changelog entry for the - migration. +The option puts the link into the version badge. The link text is the title +of the changelog entry, so you do not copy the title and the URL by hand. -The entry itself is always a single token; only a text you supply may -contain spaces. +If the identifier does not match an entry, the rendering shows a warning. +Check the identifier before you commit the change.