[CybotTM]

Documenting an issue of the Changelog-To-Doc repository takes the same lookups each time: the type and version of the changelog entry, the value for the :changelog: option, the manual and its branches, the pages that already mention the changed API, and how earlier issues about the same API were decided. Two of them are easy to miss: the issue title as the commit summary, and the patch release that shipped a 14.3.x entry.

The skill typo3-docs-changelog runs two scripts. changelog_issue.py prints these facts for an issue, with the comments on it, the pull requests that already name it, and the first release per Core branch from Gerrit. check_changelog_change.py checks a finished change: the :changelog: identifier and its version, includes that are missing on a backport branch, sentences said twice, a patch version in the running text, the commit message, and the size of a Deprecation, Breaking, or Important change compared with earlier accepted changes.

For the triage, the skill refers to the section "Triage new issues" of the page about changelog entries. Its other rules come from review comments on recent changelog pull requests. The size limits of the check come from 40 merged changelog pull requests. The skill is added to the list of skills on the page about writing with AI assistance, which now says that this skill holds rules of its own.

The skill is the first in this repository with tests and evals. The tests in tests/ run the scripts offline against three saved issues and a small git repository; run them with "python3 -m unittest discover -s skills/typo3-docs-changelog/tests". The evals in evals/evals.json give a model the output of changelog_issue.py for real issues and grade its answer with and without the skill. They use the format of the A/B runner of netresearch/skill-repo-skill. No workflow of this repository runs either of them.

Assisted-by: Claude Opus 5.5 noreply@anthropic.com
Agent-Session: b8f5fb05-02a4-4932-9730-5833a75fc773
Agent-Host: 0493f0
Signed-off-by: Sebastian Mendel info@sebastianmendel.de

[linawolf]

I would suggest we use you skill and reduce #643 to only the doucmentation

[CybotTM]

@linawolf One question for the review: which version should the version directive name for an entry in a patch-release folder such as 14.3.x?

The skill currently asks for the first release that contains the change, looked up in Gerrit. For Changelog-To-Doc#1903 that is :changed: 14.3.8 important-106077-1789503919. Earlier merged changelog PRs did it this way, and Maintainers/Changelog explains the patch release (14.3.22 in its example), but no page of the guide says which form the directive takes. Your triage comment on #1903 asks for a versionchanged "for 14.3".

1. The patch version, 14.3.8: the current rule of the skill.
2. The minor version, 14.3.

The check script reports a deviation only as a CHECK, not as a FIX. Either answer is a small change to SKILL.md and the script.

Assisted by claude-code:claude-opus-5-5 — Session b8f5fb05-02a4-4932-9730-5833a75fc773

[linawolf]

I tried the skill on #1933, #1926, #1929, and #1924 of Changelog-To-Doc.
The facts it collects are right, including the first release from
Gerrit for the 14.3.x entries.

On your question: it depends on the folder. An entry from a
patch-release folder such as 14.3.x names the first patch release that
contains it, for example 14.3.10. An entry from a minor-release folder
such as 14.3 or 14.0 names that version: 14.3 or 14.0. My comment on
#1903 should have named the patch release.

Some points I found:

1. Triage outcome: step 2 drafts only the comment. It does not say
   which labels to add, when to close the issue, or what to do when
   the Core commit already documented the change. These rules are in
   the section "Triage new issues" of
   [TASK] Describe how to triage Changelog-To-Doc issues #643.
   Could step 2 refer to that section once it is merged?
2. Rate limit: without --manuals, each API name is one code search.
   #1929 has 24 names, so the fourth issue in a row stopped with
   "GitHub API rate limit reached for /search/code". With --manuals,
   git grep reads HEAD of each clone, which can be any branch. Could
   it read origin/main, after a fetch?
3. The search only finds API names. For #1929 it found the outdated
   page in TYPO3 Explained, but not the sentence in the TypoScript
   Reference about the "default storage with UID 0 as a fallback". The
   skill could say to also search for the main terms of the changelog
   in plain words.

[CybotTM]

Thanks for trying it. The version rule you describe is what the skill and the check script already do: a 14.3.x entry gets the first patch release, a 14.3 entry gets 14.3.

Your three points are in 01f083a:

1. Step 2 now refers to "Triage new issues" in Maintainers/Changelog (the branch is rebased on [TASK] Describe how to triage Changelog-To-Doc issues #643). It keeps only what that section does not say: also search in plain words, decide per entry, and post, label, or close only when asked.
2. The GitHub code search now waits for the next minute when it hits the limit. If it still fails, the script lists the names it did not search and goes on. With --manuals, it fetches main from the TYPO3-Documentation remote of each clone and searches that instead of HEAD.
3. Step 2 asks for a search for the main terms of the changelog in plain words, with "default storage" as the example.

Assisted by claude-code:claude-opus-5-5 — Session b8f5fb05-02a4-4932-9730-5833a75fc773

[linawolf]

Thanks, all three points are fixed, and the tests run green here (92 tests, offline).

Three more things, none of them blocking:

1. The rule for the version in the directive (14.3.x → first patch release, 14.3 → 14.3) is only in the skill. I would like to add it to Maintainers/Changelog with an example, so that the skill can refer to it, as the other skills do. I can do that in a follow-up.
2. Most of the reviewer points in step 3 are not specific to changelogs. I would like to move them into the content style guide later, in a separate PR.
3. Should plugin.json get a new version, so that an installed plugin picks up the new skill?

I would squash and merge without the Agent-Session and Agent-Host trailers, which are not part of our commit message rules.

[CybotTM]

Thanks. Points 1 and 2 as follow-ups are fine with me; the skill can then refer to the guide for both. Squash without the two trailers is fine as well.

On plugin.json: the plugin lists no skills, so a new folder under skills/ is part of it without a change, and the version has stayed at 0.1.0 since #616, also for the screenshot skill in #633. I have not checked whether an installed plugin picks up new content without a version change. A version bump is the safe way, and I would do it in a separate pull request, once for all changes since 0.1.0.