Skip to content

[FEATURE] Document the :changelog: option of the version directives - #571

Open
CybotTM wants to merge 2 commits into
TYPO3-Documentation:mainfrom
CybotTM:feature/changelog-option-in-version-directives
Open

CybotTM wants to merge 2 commits into
TYPO3-Documentation:mainfrom
CybotTM:feature/changelog-option-in-version-directives

Conversation

@CybotTM

@CybotTM CybotTM commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Documents the :changelog: option that render-guides#1303 added to versionadded, versionchanged and deprecated.

Draft on purpose. The option is in render-guides main but not in 0.41.0, which is what renders docs.typo3.org today — I checked the tag rather than assuming. This should not merge before a release that carries it. Everything else is ready.

The page currently shows only the hand-written permalink in the directive body, which is exactly what the option replaces, so the new section sits after the existing ones and says so. The link text the option produces is the entry's own title, i.e. what an author writes by hand today; the difference is that a non-existent entry now produces a build warning and the unresolved-reference marker instead of a permalink that leads nowhere.

Covered: the three value forms (Core entry id, another manual's interlink shortcode plus anchor, the local #anchor), and the embedded text <entry> form for the case where the resolved title does not describe the change — an extension whose whole changelog page carries one label, for instance.

Every example is a code-block, none of them a live directive, so the page renders unchanged on the current release and nothing has to be revisited when the option ships. make test-docs passes with no warnings.

Assisted by claude-code:claude-opus-5 — Session

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 <entry>" 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 <info@sebastianmendel.de>
Agent-Session: https://claude.ai/code/session_01NxSeVq1hDnGBCqKLGcjQ6m
Agent-Host: 32116e
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
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 <entry>"
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 <info@sebastianmendel.de>
Agent-Session: https://claude.ai/code/session_01NxSeVq1hDnGBCqKLGcjQ6m
Agent-Host: 32116e
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
@CybotTM
CybotTM marked this pull request as ready for review September 17, 2026 11:43
@CybotTM

CybotTM commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

Out of draft — the content is complete and documentation is green.

One thing for whoever merges: this should not land before a render-guides release that carries the option. It is in main (render-guides#1303, merged as 3a35e418) but not in 0.41.0, which is what renders docs.typo3.org today — I read the tag rather than assuming. Nothing breaks if it merges early: every example is a code-block, not a live directive, so the page renders unchanged. It would just describe an option authors cannot use yet.

A re-read against the repo's own conventions turned up three things, all fixed in f49c4b9: the heading underline was one character short of the title, the section used -- where this file and the manual around it use - (84 occurrences against 8), and "the option takes three forms" read as if the embedded text <entry> form were a fourth — the three are ways to address the entry, and the embedded form wraps any of them.

make test-docs passes with no warnings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant