Skip to content

[FEATURE] Warn about tags TER already implies - #97

Open
CybotTM wants to merge 2 commits into
TYPO3:mainfrom
CybotTM:feature/warn-on-ter-implied-tags
Open

[FEATURE] Warn about tags TER already implies#97
CybotTM wants to merge 2 commits into
TYPO3:mainfrom
CybotTM:feature/warn-on-ter-implied-tags

Conversation

@CybotTM

@CybotTM CybotTM commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

Resolves #96, along the lines @bmack agreed to there: warning plus README update.

The rule

Every extension in TER is a TYPO3 extension, so typo3, typo3-extension, extension, cms and php narrow nothing down there. The same terms are what make a package findable on GitHub or Packagist — which is exactly why a publishing pipeline that reuses one vocabulary across registries sends them to TER.

Measured, not assumed

I first wrote the term list from that reasoning alone. Checking it against 3000 TER extensions and the three vocabularies of the top 60 by downloads changed it:

Vocabulary Platform terms Share
TER tags (625 occurrences) 5 0.8%
composer.json keywords (207) 46 22%
GitHub topics (92) ~50 54%

Two things follow. TER tags are largely clean today — the top terms are content, backend, responsive, news, typoscript — so this is preventive rather than a fix for a widespread mess. And the sources a pipeline would copy from are anything but clean, so the warning earns its place the moment tags are automated.

The measurement also corrected the list: composer.json keywords favour typo3 cms with a space (the second most common keyword overall) and GitHub topics favour typo3-cms-extension — neither was in my first draft. Rather than enumerate permutations, terms are now compared with separators stripped, so those variants and future ones collapse to one entry. Domain tags that legitimately contain separators (e-commerce, tt_news) are unaffected, and a test pins that down.

Worth noting alongside: only 134 of 3000 sampled extensions use tags at all.

Warning, not filter

 [WARNING] Every extension in TER is a TYPO3 extension, so typo3, php add no
           discoverability there. Consider tags describing what the extension
           does instead.

The request goes out unchanged. Tailor is a thin client over PUT /extension/{key}; dropping a value someone passed explicitly would be surprising, and which terms count as too generic is a judgement for the caller.

Discoverable before the run, not only after

A runtime warning arrives once a pipeline has been written and executed. The rule is therefore also in the --tags description, which is what ter:update -h prints and what someone — or a coding agent — reads while writing that pipeline:

--tags[=TAGS]   Comma-separated list of tags. Replaces the existing list. Every
                extension in TER is a TYPO3 extension, so terms like typo3,
                typo3-extension, extension or php add no discoverability there -
                prefer tags describing what the extension does.

The README section gains the same reasoning and connects it to the replace semantics documented just below it — that combination is what bites automated publishing, since every release overwrites curated tags.

Implementation

Matching lives in CommandHelper::getTagsImpliedByTer() so it is unit-tested rather than buried in the command: case-insensitive, separator-insensitive, tolerant of whitespace and empty segments, and no substring matches.

composer cs clean, composer tests:unit green — 67 tests, 183 assertions, 11 of them new.

Every extension in TER is a TYPO3 extension, so tags such as typo3,
typo3-extension, extension, cms or php narrow nothing down there. The
same terms are valuable elsewhere -- on GitHub typo3-extension is what
makes a repository findable at all, on Packagist typo3 still helps --
which is why a publishing pipeline reusing one vocabulary across
registries ends up sending them. It shows in the listing today: the news
extension carries the tag "extension".

Warn when ter:update receives such a tag, and leave the request
untouched. Tailor is a thin client over PUT /extension/{key}; silently
dropping a value someone passed explicitly would be surprising, and
which terms are "too generic" is a judgement that belongs to the caller.
A hint at the point of use costs nothing.

Also document it in the README, next to the --tags example, together
with why it matters most for automated publishing: the whole list is
replaced on every call, so a pipeline keeps overwriting curated tags.

Resolves TYPO3#96

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
@CybotTM
CybotTM marked this pull request as draft August 2, 2026 09:07
The term list was reasoned about rather than measured. Checking 3000 TER
extensions and the three vocabularies of the top 60 by downloads shows
the reasoning held but the list missed spellings that dominate in
practice: composer.json keywords favour "typo3 cms" with a space -- the
second most common keyword overall -- and GitHub topics favour
"typo3-cms-extension", the most common extension term there.

Compare with separators stripped instead of enumerating permutations, so
"typo3 cms", "typo3-cms" and "typo3cms" are one entry and future variants
are covered. Domain tags that legitimately contain separators, such as
"e-commerce" and "tt_news", are unaffected -- covered by a test.

State the rule in the --tags description as well. The warning fires only
after a pipeline has been written and run; the option description is what
`ter:update -h` prints, which is where someone -- or a coding agent --
looks before writing it.

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
@CybotTM

CybotTM commented Aug 2, 2026

Copy link
Copy Markdown
Contributor Author

Heads-up while reviewing: I filed #98 after trying to use --tags for real. It stores only the first comma-separated element and reports failure while doing so, so the README example --tags=some-tag,another-tag currently sets one tag and returns a non-zero exit.

That does not invalidate this PR — the guidance is about which tags to choose and stays correct — but the two are worth reading together, and the README wording here may want a pointer once #98 is resolved. Happy to fold a note in if you prefer.

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.

ter:update --tags: warn when a tag is already implied by TER

1 participant