You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Decentralized meta and links object documentation (Issue #136)
As described in issue #136, because of the per-event versioning scheme
it is untenable to keep link type documentation central and separate from
event types. When link types are changed, this constitutes an event
version change. Therefore, the link types of each event type must be
documented each respective event type documentation.
the-links-object.md has been preserved, but only contains general
information. The repository has been searched for occurrences of
the-links-object.md and has been updated accordingly.
As described by Issue #136, the per-event versioning scheme
requires that even common syntax be described on a per-event basis,
lest the documentation and/or versioning break down.
This commit moves the meta object documentation into the
documentation of each respective event.
Copy file name to clipboardExpand all lines: eiffel-syntax-and-usage/event-structure.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -31,4 +31,4 @@ __Description:__ This object contains all fields specific to the event type –
31
31
## links
32
32
__Type:__ Object
33
33
__Required:__ Yes
34
-
__Description:__ This object contains all trace links to other Eiffel events. It is described in detail [here](./the-links-object.md).
34
+
__Description:__ This object contains all types of links to other Eiffel events. Its usage and syntax is described [here](./the-links-object.md), while the full list of optional and required links is described in the documentation of each respective event type..
For a full list of individual contributors, please see the commit history.
4
4
5
5
Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,7 +16,7 @@
16
16
--->
17
17
18
18
# The Links Object
19
-
The __links__ object is an array of trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occured. Each trace link is a tuple consisting of a type and a UUID corresponding to the __meta.id__ of the target event, on String format.
19
+
The __links__ object is an array of trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occurred. Each trace link is a tuple consisting of a type and a UUID corresponding to the __meta.id__ of the target event, on String format.
20
20
21
21
Some link types allow multiple trace links, whereas others only allow one.
22
22
@@ -27,170 +27,4 @@ Example syntax of a simple __links__ object:
__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__.
__Description:__ Identifies the activity or test suite of which the event constitutes a part. SHOULD not be used in conjunction with __CAUSE__, see above. Note that multiple layers may be modeled using __CONTEXT__, e.g. an activity being part of another activity.
__Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to.
__Description:__ Declares the activity execution the event relates to. In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) acts as a handle for the activity execution. This differs from __CONTEXT__. In __ACTIVITY_EXECUTION__ the source carries information pertaining to the target (i.e. the activity started, finished or was canceled). In __CONTEXT__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite).
__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the engineering artifact the event represents, e.g. the previous version of the artifact, the previous version of the composition etc. The target event type SHALL be the same as the source event type.
__Description:__ Identifies the composition from which an artifact declared by [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) was built, or the composition for which an already existing artifact is declared reused by [EiffelArtifactReusedEvent](../eiffel-vocabulary/EiffelArtifactReusedEvent.md).
__Description:__ Identifies an element and/or sub-composition of the composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change.
__Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution.
__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution started, finished or was canceled). In __CONTEXT__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite).
__Description:__ When declared in an [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md), this link signifies that the test suite groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md).
__Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation.
__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them via __SUB_CONFIDENCE_LEVEL__. This is intended for purely descriptive, rather than prescriptive, use.
__Description:__ This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) that is reused; in other words, the artifact that is not rebuilt for a given composition.
__Description:__ Used to declare the basis on which the verification statement(s) of [EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) have been issued.
30
+
The full list of optional and required links is described in the documentation of each respective event type.
0 commit comments