90907[DOCS] Improve hint for annotation scope in changelog for #107229
Commit message
Review
-
Code review CR +2 Done
- Garvin Hicking +2
- Torben Hansen +1
- Anja Leichsenring +1
- Lina Wolf +1
-
Verified V +2 Done
- Garvin Hicking +2
- Torben Hansen +1
- Anja Leichsenring +1
- core-ci +1 CI
Issues 2
Files 1
Review log 1415
-
Elias Häußler uploaded patch set 1 10/06/25, 06:57
-
Torben Hansen voted on patch set 1 CR +1 V +1 10/06/25, 07:03
-
Anja Leichsenring voted on patch set 1 CR +1 V +1 10/06/25, 07:10
-
Garvin Hicking commented on patch set 1 V -1 10/06/25, 07:18
Thanks Elias! Waiting for @112@linawolf.de to approve or comment, since she brought it up and should have a say -
core-ci voted on patch set 1 V +1 10/06/25, 07:22 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86059
-
Lina Wolf commented on patch set 1 CR -1 10/06/25, 07:33
In the official docs we called the whole concept of attaching this additional information to models and controllers "Annotations": [Annotations in Extbase ](https://docs.typo3.org/permalink/t3coreapi:extbase-annotations) Even if the the syntax for validate etc used was native PHP Attribute, we spoke about "Annotations as PHP attribute" vs "Annotations as doc block content". This wording is used all over the docs and has been for a long time. So if we say annotations have been removed (and not the doc block syntax of annotations has been removed) we are opening the doors for any kind of panic and misunderstanding. I prepared an array to rename the concept: https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/6071 But I still think it is a very bad idea to rename the whole concept when all that is changing to the extension developers is the SYNTAX, not the concept of Extbase Annotations (Validate, Transient, Lazy etc) itself is to be changed. Yes under the hood the technology was changed. But the only thing that changes to the average developer is the SYNTAX that has to be used... If we are to rename the concept (not syntax) we have to do that more prominently. I would, however suggest to keep calling the concept "Annotation" while the new syntax is called native PHP attribute. **Extbase Annotations are only supported in native PHP Attribute Syntax** Something along those lines. -
Garvin Hicking commented on patch set 1 V 0 10/06/25, 07:49
Reply
soapbox: We cannot keep a wording around from a time before introduction of Attributes, just because we are used to that. Attributes have shifted this world, so we must make a distinction of "phpdoc annotations" and "attributes" now. The docs will need adjustment for this, I'm afraid. The sentence "Extbase annotations... PHP Attribute syntax" is too messy. What we should do in the docs is to say: "Extbase annotations have evolved. Formerly, Extbase Annotations utilized the Doctrine Annotation package to have a namespace for these specific annotations. When PHP evolved to utilize native Attributes for introspection of metadata, Extbase has shifted to these as well. This is why Extbase Annotations are no longer used as a term, but Extbase Attributes." I don't have a good example, only a bad one. Say we change from Fluid to Twig, then the docs cannot keep using "Fluid templates" for template, only because it was established everywhere. It would be technically incorrect. What we could do is to try to establish "Extbase property metadata" or something like that, to avoid both "annotation" or "attribute" as a specific way of implementation. But that would mean changing it anyways. PHP attributes will stay with us forever now, I believe. So we should feel free to make that step to embrace this new naming and not carr a legacy ambiguous wording. -
Lina Wolf commented on patch set 1 10/06/25, 07:54
Reply
To call a concept by the syntax used to transport it is not a good practice. In PHP 9 the syntax might change another time, who knows. The abstract concept should not be called by the same name as the syntax used to transport it. Annotations is Anmerkungen in german. Attributes is Eigenschaften. Both of it refer to syntax. The concept should have a name that is independant from the syntax. If we change it now for very good reason we should change it to something that can keep its name forever.. -
Lina Wolf commented on patch set 1 10/06/25, 08:01
Reply
It might make more sense to move attributes around validation #Validate and #Novalidate into namespace Validation and everything like #Lazy #Transient etc into Namespace Persistence? -
Garvin Hicking commented on patch set 1 10/06/25, 08:11
Reply
> If we change it now for very good reason we should change it to something that can keep its name forever.. I'm open for suggestions, but it cannot be "Extbase annotations", and probably also not "Extbase attributes" given this line of argumentation. Apart from "Extbase property metadata" I have no idea. We should do this seperately, and for now move on with this specific patch though. IMO separating the validation/persistence attributes into specific namespace would not improve much. For me, the common ground is "attribute", and not "persistence" or "validation". I don't think we need fragmentation for these and make migration conditional. Also it would then implement two "use" statements where one might be sufficient. But this is also a seperate topic to discuss I think. Gerrit isn't the place for this though. I would suggest: 1. Discuss the extbase nomenclature in the documentation SIG 2. Create a separate patch or forge issue or coredev-slack thread for dividing the attributes and gather feedback If that's acceptable, we could move on and resolve this thread here for now? -
Lina Wolf commented on patch set 1 CR +1 10/06/25, 09:02
Ok, works for me -
Lina Wolf commented on patch set 1 10/06/25, 09:03
Reply
Done -
Lina Wolf commented on patch set 1 10/06/25, 09:03
Reply
Done -
Garvin Hicking voted on patch set 1 CR +2 V +2 10/06/25, 13:40
-
Garvin Hicking merged patch set 2 10/06/25, 13:40