diff --git a/Documentation/Reference/ReStructuredText/Content/Versions.rst b/Documentation/Reference/ReStructuredText/Content/Versions.rst index 6e2450db..9b3d549b 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 entry can be addressed in three ways: + +.. 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.