[TASK] Versions directives: reference released versions only - #544
Closed
CybotTM wants to merge 1 commit into
Closed
[TASK] Versions directives: reference released versions only#544CybotTM wants to merge 1 commit into
CybotTM wants to merge 1 commit into
Conversation
CybotTM
marked this pull request as draft
August 14, 2026 12:47
Document that version directives must reference released TYPO3 versions only - plans change, published versionadded directives stay. Assisted-by: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
CybotTM
force-pushed
the
docs/versions-released-only
branch
from
August 14, 2026 13:23
369d58c to
90612f1
Compare
CybotTM
changed the title
CybotTM
marked this pull request as ready for review
August 14, 2026 13:30
linawolf
reviewed
Aug 15, 2026
linawolf
left a comment
linawolf
left a comment
Member
There was a problem hiding this comment.
That note is actually not correct. While the Core Team works on TYPO3 15.0 we already document it in the main version using versionadded:: 15.0 etc. We are trying to have the documentation ready when a release is beeing made and that means we are working on it before the version has actually been released.
Contributor
Author
|
Closing this — the note is simply wrong, thank you for catching it. I assumed version directives should trail the releases, and that is not how the Core Team works: documenting TYPO3 15.0 with Nothing here is worth salvaging under a different wording, so I would rather withdraw it than rewrite it into something narrower. |
CybotTM
added a commit
to netresearch/typo3-docs-skill
that referenced
this pull request
Aug 17, 2026
The skill forbade `versionadded` for anything not yet released, and enforced it via TD-41. That rule contradicts established practice: the Core Team documents TYPO3 15.0 with `versionadded:: 15.0` while 15.0 is being built, so the documentation is ready when the release lands. The same claim was proposed upstream as TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#544 and withdrawn on 2026-08-15 after that feedback — but the local copy kept enforcing it, which is the drift this skill's own authority rules describe, in the direction where a gate holds a rule green that should not exist. The concern behind the rule was narrower than the rule: writing a directive before it is settled whether the next release is 1.3.0 or 2.0.0. That is rare, tolerable, and decidable by machine once a higher version exists — so it becomes the check instead of a prohibition. check-unreleased-versions.sh now warns only when a documented number was skipped: not released, and some released version is higher. Measured over six cases — the pending next version, the released version, a skipped version, a file mixing pending and skipped, no directives at all, and a non-repo — plus the `v`-prefixed tag spelling. The old check could not tell the first case from the third: it fired identically on both, so it flagged correct practice. The `ext_emconf.php` escape from the old script is gone as redundant, not lost: a declared-but-untagged version is by definition the pending release and is silent under the new rule. TD-41 keeps severity `warning`; only its description changes. Assisted-by: claude-code:claude-fable-5 Agent-Session: https://claude.ai/code/session_012NiLDH3iWw8CVdAnimJbF8 Agent-Host: 32116e Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
CybotTM
added a commit
to netresearch/typo3-docs-skill
that referenced
this pull request
Aug 17, 2026
…forcing the old rule (#82) The skill forbade `versionadded` for anything not yet released and enforced it through checkpoint TD-41. That contradicts established practice: the Core Team documents TYPO3 15.0 with `versionadded:: 15.0` while 15.0 is being built, so the documentation is ready when the release lands. The same claim was proposed upstream as [TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#544](TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#544) and withdrawn on 2026-08-15 after exactly that feedback — while the local copy kept enforcing it. That is the drift this skill's own authority rules describe, in the direction where a gate holds a rule green that should not exist. **The concern behind the rule was narrower than the rule:** writing a directive before it is settled whether the next release is `1.3.0` or `2.0.0`. Rare, visible on the next release, and cheap to correct when noticed. **The first attempt kept a narrowed check. Review measured it and it had to go.** Three ordinary situations produced a warning while the documentation was correct: | Situation | What the check did | |---|---| | shallow clone or `--no-tags` CI checkout | reported a version the repo demonstrably shipped as never shipped, quoting a "highest released version" from a truncated tag list | | two-component number, `13.4` against a `13.4.0` tag | never extracted the number at all — including `versionadded:: 15.0`, the example the new prose itself gives, and the shape `assets/AGENTS.md` templates into consumer repos | | patch release on a maintenance line, `1.2.1` while `2.0.0` exists | flagged as skipped; the `ext_emconf.php` escape I had removed as "redundant" was covering exactly this | Each is the harm the retired prohibition caused — a warning against correct practice. Hardening past them needs shallow-repo detection, version normalisation, maintenance-line awareness and a way to ignore numbers inside RST examples. That is disproportionate for this defect, so `check-unreleased-versions.sh` and TD-41 are removed, with a note at the checkpoint slot and the reasoning in `rst-syntax.md`. The script also carried `printf | grep -qx`, which inverts under `pipefail` once the tag list exceeds the pipe buffer — measured 6 of 6 runs answering "not released" for a version that was in the list, at 189 KB. I had a memory naming that exact trap and wrote it anyway. **Sweep of what the first commit missed.** The retired rule survived in four more places, two of them labelled as a normative skill rule and pointing the reader at the section that now says the opposite: `content-directives.md`, `typo3-directives.md`, `extraction-patterns.md` and the script listing in `scripts-guide.md`. All corrected. The Versions page is now referenced by permalink in all six places instead of two different ways inside one file. No eval asserted the retired rule. _Assisted by claude-code:claude-fable-5 — [Session](https://claude.ai/code/session_012NiLDH3iWw8CVdAnimJbF8)_
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents that version directives must reference released TYPO3 versions only — plans change, published versionadded directives stay.