Clarify naming conventions for link types

[e-pettersson-ericsson]

Description

I couldn't find any explicit naming conventions in regards to link types in the event guidelines.

All existing link types seems to be nouns, is this some unwritten rule? Why is that so? Are verbs not allowed? I'm missing documentation about what is allowed and what is not.

Motivation

It will be easier to understand when/if someone wants extend the protocol.

Exemplification

Extend the documentation about the links object with a clear rule saying what is allowed or not.

Benefits

Clarified documentation.

Possible Drawbacks

None that I can think of.

[e-backmark-ericsson]

I agree that it seems to be missing. It should probably be stated on this page: https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/event-design-guidelines.md and linked from the links guidelines page you provided. I currently don't have any suggestion on if the link types should be restricted to a certain word class or so, but it sounds reasonable to do to ease for new link types to be defined and to clarify what links should be used for.

[magnusbaeck]

Looking at the existing link types the following patterns (depending on whether the link type allows multiple targets) applies in all or nearly all cases:

<target> is the <source>'s <type>
<target> is one of the <source>'s <type>s

Examples:

ActT is the ActS's ACTIVITY_EXECUTION
ArtC is one of the ActT's CAUSEs
SCC is the SCS's CHANGE
ArtC is the ArtP's ARTIFACT
ED is the ArtC's ENVIRONMENT

This probably means that link types always will be nouns, but I think documenting these pattern sentences is more useful than saying "the link type should be a noun".

[magnusbaeck]

Below is an extraction of all link types for all (source) events and I can't find one that doesn't fit the previously described pattern.

$ for i in *.md ; do echo $i | sed 's/\.md//' ; sed -n 's/^### \([A-Z][A-Z_]*$\)/    \1/p' $i ; done
EiffelActivityCanceledEvent
    ACTIVITY_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelActivityFinishedEvent
    ACTIVITY_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelActivityStartedEvent
    ACTIVITY_EXECUTION
    PREVIOUS_ACTIVITY_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelActivityTriggeredEvent
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelAnnouncementPublishedEvent
    MODIFIED_ANNOUNCEMENT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelArtifactCreatedEvent
    COMPOSITION
    ENVIRONMENT
    PREVIOUS_VERSION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelArtifactPublishedEvent
    ARTIFACT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelArtifactReusedEvent
    COMPOSITION
    REUSED_ARTIFACT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelCompositionDefinedEvent
    ELEMENT
    PREVIOUS_VERSION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelConfidenceLevelModifiedEvent
    SUBJECT
    SUB_CONFIDENCE_LEVEL
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelEnvironmentDefinedEvent
    PREVIOUS_VERSION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelFlowContextDefinedEvent
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelIssueDefinedEvent
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelIssueVerifiedEvent
    SUCCESSFUL_ISSUE
    FAILED_ISSUE
    INCONCLUSIVE_ISSUE
    IUT
    VERIFICATION_BASIS
    ENVIRONMENT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelSourceChangeCreatedEvent
    BASE
    PREVIOUS_VERSION
    PARTIALLY_RESOLVED_ISSUE
    RESOLVED_ISSUE
    DERESOLVED_ISSUE
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelSourceChangeSubmittedEvent
    CHANGE
    PREVIOUS_VERSION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestCaseCanceledEvent
    TEST_CASE_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestCaseFinishedEvent
    TEST_CASE_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestCaseStartedEvent
    TEST_CASE_EXECUTION
    ENVIRONMENT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestCaseTriggeredEvent
    IUT
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestExecutionRecipeCollectionCreatedEvent
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestSuiteFinishedEvent
    TEST_SUITE_EXECUTION
    CAUSE
    CONTEXT
    FLOW_CONTEXT
EiffelTestSuiteStartedEvent
    TERC
    CAUSE
    CONTEXT
    FLOW_CONTEXT