This email serves to outline planned changed to the Entity class hierarchy so they can be held into account for development. This has no immediate impact on user facing functionality.
Right now we have an Entity class that holds an EntityId, a Fingerprint and a list of Claim. Item derives from Entity and adds a list of SiteLink, as well as changing the list of Claim to a list of Statement. Property also derives from Entity and adds only a property type field. In the future we will have more types of entities, such as a QueryEntity which holds a query description and entities for Wikimedia Commons.
The problem is that these different types of entities are made up of different things, and the intersection between all of them is only that they have an id. Hence the code sharing by inheritance approach we currently have is definitely a mistake. The thing we are aiming for is to use more specific interfaces and the things that make up entities.
Example: You have a list of items and properties, and you want to store their terms into a database table for lookup purposes. Rather than having the "term store" take an Entity and so increase the assumption that all entities have terms, only require what is strictly needed. In this case an EntityId and a Fingerprint (which contains the terms).
$termStore->insertTermsForEntity( Entity $entity )
$termStore->insertTermsForEntity( EntityId $id, Fingerprint $fingerprint )
Any type hint against Entity suggests an assumption we already know will not hold. Hence avoid parameters and fields of type Entity. Mirroring the Entity class hierarchy, such as EntityDiff and ItemDiff, is another thing to avoid. New occurrences of any of these should not be added, so please -1 any commits that do so.
To avoid confusion: it is perfectly fine to have a parameter or field of a concrete entity type, such as Item or Property.
Cheers
Software craftsmanship advocate
Evil software architect at Wikimedia Germany
~=[,,_,,]:3