From 155f58150021d4496a14762044c7a04f12bd042c Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 17 Sep 2026 13:01:46 +0200 Subject: [PATCH 1/2] [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 f49c4b9434487dc9d24c178cbb8c1fcae6ba0ac1 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 17 Sep 2026 13:38:30 +0200 Subject: [PATCH 2/2] [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: