Skip to content

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

Merged
linawolf merged 3 commits into
TYPO3-Documentation:mainfrom
CybotTM:feature/changelog-option-in-version-directives
Oct 1, 2026
Merged

[FEATURE] Document the :changelog: option of the version directives#571
linawolf merged 3 commits into
TYPO3-Documentation:mainfrom
CybotTM:feature/changelog-option-in-version-directives

Conversation

@CybotTM

@CybotTM CybotTM commented Sep 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Documents the :changelog: option of versionadded, versionchanged and deprecated. The option was added in render-guides#1303 and is part of render-guides 0.42.0 and later, so the PR can merge now.

The new section shows a code example and the rendered directive. The option puts the link to the changelog entry into the version badge. The link text is the title of the entry. The section covers only entries of the TYPO3 Core changelog.

An identifier that does not match an entry gives a build warning. I tested this with feature-999999-1111111111: the renderer logged Inventory link with key "changelog:feature-999999-1111111111" ... not found, and make test-docs failed.

make test-docs passes with render-guides latest (0.44.0). The rendered badge links to "Feature: #107628 - Improved backend module naming and structure".

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

@CybotTM CybotTM mentioned this pull request Sep 17, 2026
Merged
@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.

linawolf
linawolf reviewed Sep 22, 2026
View reviewed changes
Comment thread Documentation/Reference/ReStructuredText/Content/Versions.rst
linawolf
linawolf reviewed Sep 22, 2026
View reviewed changes
Comment thread Documentation/Reference/ReStructuredText/Content/Versions.rst Outdated
linawolf
linawolf reviewed Sep 22, 2026
View reviewed changes
Comment thread Documentation/Reference/ReStructuredText/Content/Versions.rst Outdated
linawolf
linawolf reviewed Sep 22, 2026
View reviewed changes
Comment thread Documentation/Reference/ReStructuredText/Content/Versions.rst Outdated
@CybotTM
[FEATURE] Document the :changelog: option of the version directives
5a25848 
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>
@CybotTM
[TASK] Fix the house style of the :changelog: section
2c03517 
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
[TASK] Show the rendered :changelog: option and keep to Core entries
5f5f9e9 
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 <entry>"
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 <noreply@anthropic.com>
Agent-Session: https://claude.ai/code/session_01Q23BuF75uotqYJZhYxgbn9
Agent-Host: 0493f0
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
@CybotTM
CybotTM force-pushed the feature/changelog-option-in-version-directives branch from f49c4b9 to 5f5f9e9 Compare September 26, 2026 22:37
@CybotTM CybotTM mentioned this pull request Sep 26, 2026
Merged
4 of 11 tasks
CybotTM added a commit to netresearch/retro-skill that referenced this pull request Sep 26, 2026
@CybotTM
fix(collect-review-findings): prefer a commit authored after the find…
3d6c7d0 
…ing (#158)

After this merges, `collect-review-findings.py` reports as
`commit_after` the earliest commit whose author date and committer date
are both after the finding. Only when no such commit exists does it fall
back to the earliest commit by committer date, as before.

**Why.** `first_commit_after` took the earliest commit by committer
date. A rebase gives every replayed commit a new committer date, so on a
rebased branch the PR's first commit qualified even when it was written
days before the finding. Replayed commits often share one committer
date, and `min` then returns the first in list order.

**Observed case.** On
`TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#571` four review
threads opened 2026-09-22 were reported as `commit after: 5a258485`. The
PR's commits (author date / committer date): 5a258485
2026-09-17T11:01:46Z / 2026-09-26T22:34:28Z, 2c035170
2026-09-17T11:38:30Z / 2026-09-26T22:34:28Z, 5f5f9e9a
2026-09-26T22:35:53Z / 2026-09-26T22:37:09Z. The first two were written
before the threads and only replayed after them; 5f5f9e9a answered them.
With this change the script run against the live PR reports 5f5f9e9a for
all four threads.

**Rule.** Among commits with a committer date after the finding, prefer
those whose author date is also after it, earliest by committer date. An
amended or rebased fix whose author date predates the finding is only
chosen when no commit was written after the finding; the field stays a
necessary sign, not proof. The GitHub query now reads `authoredDate`;
GitLab's commit list already carries `authored_date`. The docstring and
the `commit_after` row in `friction-catalog.md` say the same.

**Tests.** Two regression tests are built from the real case: one with
the three #571 commits and the 2026-09-22T14:40:28Z thread on the GitHub
path, one on the GitLab fixture with both commits replayed after the
thread. A third pins the fallback. Against the unfixed script the first
two fail (`['5a258485'] != ['5f5f9e9a']`, and `a1b2c3d…` instead of
`5b1e2c0…`), 182 tests run, failures=2. Removing the fallback instead
fails the fallback test and the two existing fixture tests (182 run,
failures=2, errors=1). With the fix: `unittest discover -s tests` 622
tests OK; `py_compile`, `validate-evals.py`, `ruff format --check` and
`ruff check` exit 0.

_Assisted by claude-code:claude-opus-5.5 —
[Session](https://claude.ai/code/session_01Q23BuF75uotqYJZhYxgbn9)_
CybotTM added a commit to netresearch/typo3-docs-skill that referenced this pull request Sep 26, 2026
@CybotTM
docs: document :changelog: option, headline roles, minimal-test output (
1692b9a 
#156)

Merging this adds three documentation facts to the typo3-docs skill
references: the `:changelog:` option of the version directives, a rule
against text roles in headlines, and what `--minimal-test` writes to
disk. No script, checkpoint or version changes.

## Summary

- `references/typo3-directives.md`, "Version Information": the
`:changelog:` option of `versionadded`, `versionchanged` and
`deprecated`. It exists in render-guides 0.42.0 and later
(TYPO3-Documentation/render-guides#1303). The value is a Core changelog
entry identifier `<type>-<issue>-<timestamp>`; the version badge links
to the entry, with the entry title as link text. An unknown identifier
logs an `Inventory link with key "changelog:<id>"` warning, and a
`--minimal-test` render exits non-zero. The manual does not document the
option yet; relates to
TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#571, which proposes it.
- `references/rst-syntax.md`, "Headings": do not use `:rst:`, `:php:`,
`:typoscript:` or other text roles in a headline; use plain inline code.
Source: docs team review comment on
TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#571.
- `references/rendering.md`: `--minimal-test` writes only
`Documentation-GENERATED-temp/singlehtml/Index.html`, so check rendered
HTML there; per-page HTML files do not exist in that mode.

Both new rules carry `[regression]`. The repository's precedent for a
measured fact that the manual lacks and an upstream PR proposes is the
`--fail-on-log` caveat in `rendering.md`, which uses `[regression]`.
`canonical-sources.md` defines `[regression]` as guarding an observed
agent failure, so the fit is not exact. When #571 merges, the
`:changelog:` paragraph should shrink to an `[upstream]` reference, per
`canonical-sources.md`.

## Type of Change

- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change
- [x] Documentation update
- [ ] Refactoring / code quality
- [ ] CI / build / dependencies

## Checklist

- [x] Commits are signed (`-S`) and signed-off (`--signoff`)
- [x] Commits follow [Conventional
Commits](https://www.conventionalcommits.org/) format
- [ ] Tests added/updated for changed behavior (not applicable:
reference text only)
- [x] Documentation updated (README, AGENTS.md, CHANGELOG, or inline
docs)
- [ ] CI passes (lint, tests, static analysis)

## Test Plan

- `uvx pre-commit run --files <the three files>`: all applicable hooks
passed, markdownlint included.
- `uvx pre-commit run validate-skill --all-files`: passed.
- `bash scripts/verify-harness.sh`: exit 0.
- `bash tests/check-changelog-version-coverage.sh` and `bash
tests/checkpoint-scripts.sh`: exit 0.
- The RST heading underlines in the new example match their titles (51
and 46 characters).

_Assisted by claude-code:claude-opus-5.5 —
[Session](https://claude.ai/code/session_01Q23BuF75uotqYJZhYxgbn9)_
@linawolf
linawolf merged commit 2d75b97 into TYPO3-Documentation:main Oct 1, 2026
1 check passed
@linawolf

linawolf commented Oct 1, 2026

Copy link
Copy Markdown
Member

I think there are just so many ways that an extension can document their changelog. You can have them in a markdown or pure text file, you can have them in rst but not each entry on one page, ... some ppl only have headlines per version etc

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

Reviewers

@linawolf linawolf linawolf approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@CybotTM @linawolf