search

ebu / ebucoreplus

Maintenance and development of the EBUCorePlus
MIT License
23 stars 6 forks source link

299 refactoring renaming property cluster 03 #331

Closed alexander-schulze closed 2 weeks ago

alexander-schulze commented 1 month ago

This pull request includes the renaming of ten object properties.

Reviewers:

alexander-schulze commented 3 weeks ago

@JuergenGrupp @aro-max Looking forward to your feedback.

alexander-schulze commented 3 weeks ago

@JuergenGrupp The object property name has been changed from uses to hasRegistration.

aro-max commented 2 weeks ago

Thank you @alexander-schulze I agree with @JuergenGrupp about 'uses', I have some questions :

isReleasedBy' to 'isOrderedBy': 'isOrderedBy' seems to shift the focus to the ordering entity, which may not always be the releasing entity.

isReleasedBy: Indicates the entity that made the resource available to the public. isOrderedBy: Implies the entity that requested or initiated the creation or distribution of the resource.

isScheduledOn' to 'isPublishedBy': This change specifies the entity responsible for publishing, which may be different from scheduling. Typically for publication on platforms

logsPublicationEvent' to 'logs': This simplifies the property name, but may lose some specificity regarding what is being logged. It could be logsPublication.

JuergenGrupp commented 2 weeks ago

Thank you @aro-max for your feedback and questions!

I will answer them in 3 blocks:

1) isOrderedBy

aro-max:

´isReleasedBy' to 'isOrderedBy': 'isOrderedBy' seems to shift the focus to the ordering entity, which may not always be the releasing entity.

JG: a) There is a typo in the description of this pull request: ´isReleasedBy´ is not renamed to ´isOrderedBy´, but to ´isOfferedBy´. b) The property is renamed to ´isOfferedBy`because it is the inverse of ´offers´ in the following statement:

I think this renaming is in accordance with our guidelines and we should stick with it.

2) isPublishedBy

aro-max:

´isScheduledOn' to 'isPublishedBy': This change specifies the entity responsible for publishing, which may be different from scheduling. Typically for publication on platforms.

JG: a) The property´isScheduledOn´ is renamed to ´isPublishedBy´ because it is the inverse of ´publishes´ in the following statement:

I think the renaming is in accordance with our guidelines and we should stick with it.

3) logs

aro-max:

logsPublicationEvent' to 'logs': This simplifies the property name but may lose some specificity regarding what is being logged. It could be logsPublication.

JG: In earlier discussions we noted cases of overly specific property names, especially when they only repeated the name of the class that they pointed to: “logsPublicationEvent PublicationEvent”. The semantically more appropriate way is to generalize the name of the property, especially if the generalized name does not hide any of the desired information: “logs PublicationEvent” and may also be used in a similar meaning with other classes (not existing example): “ConsumptionLog logs ConsumptionEvent”. Both uses of “logs” are similar correct, describing what the “…Log”-class really does.

If the desire is to have more distinction, then the property can still be subclassed. When in need of search conditions, they can include the class that is pointed to. Instead of the search phrase “find all objects that ´logsPublicationEvent´” the phrase “find all objects that ´logs´ ´PublicationEvent´” (Note the space between “logs” and “PublicationEvent”). Finally, the ´logs´ property could be used in search phrases to access any type of Log, for any Event, not only Publication or Consumption.

I think the renaming is appropriate and in accordance with our guidelines and we should stick with it.

@aro-max : I will merge the changes now. If we change our minds on any of the namings above any time later, we will create a new issue and propose a new pull request.